Your Data · Attack Surface

`get_open_ports`

Which ports are open on a specific asset? Resolves the target (hostname, FQDN, or IP) within your assets and returns its open ports plus the detected service on each. Costs 1 credit.

POST

tools/call

Cost: 1 credit per successful call · Scope: mcp:org · Response shape: jsonb

Returns data scoped to your own organisation only — the organisation is resolved from your API key and injected server-side, never read from the request.

Parameters

targetstringrequired

The asset to resolve: a hostname, FQDN, or IP address. Accepted length: 1–255 characters. For example, autodiscover.precursorsecurity.com or 203.0.113.10.

Example invocation

Ask your agent: "Which ports are open on autodiscover.precursorsecurity.com?"

curl -s https://api.precursorintelligence.com/functions/v1/mcp \
  -H "Authorization: Bearer $PRECURSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_open_ports","arguments":{"target":"autodiscover.precursorsecurity.com"}}}'

Response

result.content[0].text (parsed)

{
  "target": "autodiscover.precursorsecurity.com",
  "count": 2,
  "open_ports": [
    {
      "hostname": "autodiscover",
      "fqdn": "autodiscover.precursorsecurity.com",
      "ip": "40.99.153.136",
      "port_number": 443,
      "protocol": "tcp",
      "state": "open",
      "service_name": "https",
      "service_product": "Microsoft IIS httpd",
      "service_version": "10.0",
      "banner": "Server: Microsoft-IIS/10.0"
    },
    {
      "hostname": "autodiscover",
      "fqdn": "autodiscover.precursorsecurity.com",
      "ip": "40.99.153.136",
      "port_number": 80,
      "protocol": "tcp",
      "state": "open",
      "service_name": "http",
      "service_product": "Microsoft IIS httpd",
      "service_version": "10.0",
      "banner": "Server: Microsoft-IIS/10.0"
    }
  ],
  "generated_at": "2026-06-18T08:15:00.000Z"
}

The full MCP envelope, including _meta.precursor with request_id, credits, and response_truncated, is documented in Response Format.

Response fields

targetstringoptional

The target value resolved for this request, echoed from the request.

countintegeroptional

Number of open ports returned (equals open_ports.length).

open_portsarrayoptional

Open ports detected on the resolved asset. Each object contains the fields below.

open_ports[].hostnamestringoptional

Short hostname of the asset.

open_ports[].fqdnstringoptional

Fully qualified domain name of the asset.

open_ports[].ipstringoptional

IP address the port was observed on, e.g. 40.99.153.136.

open_ports[].port_numberintegeroptional

Port number, e.g. 443.

open_ports[].protocolstringoptional

Transport protocol, e.g. tcp, udp.

open_ports[].statestringoptional

Port state from the most recent scan, e.g. open.

open_ports[].service_namestring | nulloptional

Detected service name, e.g. https, http, ssh.

open_ports[].service_productstring | nulloptional

Detected service product, e.g. Microsoft IIS httpd, OpenSSH.

open_ports[].service_versionstring | nulloptional

Detected service version, e.g. 10.0.

open_ports[].bannerstring | nulloptional

Raw service banner captured during the scan, when available.

generated_atstringoptional

ISO 8601 timestamp indicating when this response was generated.

Errors

Code	Message	When
`-32602`	`invalid_params: target: required_string`	The `target` argument is missing.
`-32602`	`invalid_params: target: invalid_target`	`target` is blank or exceeds 255 characters.
`-32001`	`unauthorized`	The API key is invalid/revoked, the IP is not allowed, or the key lacks the `mcp:org` scope.
`-32002`	`insufficient_credits`	Your credit balance is zero; top up from the dashboard
`-32603`	`internal`	Unexpected server error; the credit is automatically refunded

If the target is well-formed but does not resolve to any asset in your organisation, the tool returns a successful response with an empty open_ports array and count of 0.

For a complete reference of JSON-RPC error codes, see Errors.