← Back to blog

Port Checker API: Check If a TCP Port Is Open from the Cloud

October 6, 2026 · Eric · 7 min read

Agents are bad at questions like “is port 5432 reachable from outside the VPC?” The honest answer usually involves SSH, nc, or telnet, which most sandboxes and hosted agent runtimes do not allow. The Port Checker on Agent Media Tools answers it with one HTTP GET: it opens a TCP connection from the server side and reports whether the port accepted it.

There is no API key, no flexible-credit charge, and no install. Two endpoints cover the job: a single-port probe and a 20-port sweep of the usual suspects (SSH, HTTP, HTTPS, MySQL, Postgres, Redis, MongoDB, and friends). Below: request and response shapes, reading “refused” versus “timed out,” a Python example, and honest limits.

Why check a port through an API instead of a shell

A local port check answers a different question than a remote one. When you run nc -zv host 443 from your laptop, you learn whether your network can reach the host. When a hosted agent runs the same probe, you learn what any public client sees. Those answers diverge constantly: a firewall rule that only allows your office IP, a security group that opens 443 to the world but 22 to nobody, or a container bound to 127.0.0.1 instead of 0.0.0.0.

Doing it from a third-party endpoint also removes local dependencies: no raw socket code in your tool-calling layer, no nmap install, no shell access, and no risk of an agent typing a scan command against the wrong target. The response is structured JSON, so an agent branches on open instead of parsing terminal output.

The two endpoints

EndpointWhat it doesKey query params
GET /api/port/check Opens one TCP connection to host:port and reports whether it succeeded. host, port (1–65535), optional timeout (500–15000 ms, default 3000)
GET /api/port/scan-common Probes 20 common ports on one host in parallel and returns the ones that are open. host only

Both accept a bare hostname or a full URL — https://example.com/path is normalized to example.com first. The catalog entry lives at /tools, and agents can read the whole tool list from GET /api/tools.

Check one port with curl

curl "https://agentmediatools.com/api/port/check?host=example.com&port=443"

A hit looks like this:

{
  "success": true,
  "host": "example.com",
  "port": 443,
  "service": "HTTPS",
  "open": true,
  "detail": "Port is open and accepting connections",
  "elapsed_ms": 42,
  "timeout_ms": 3000
}

Four fields carry the meaning:

For a slow load balancer or a saturated firewall, raise the timeout:

curl "https://agentmediatools.com/api/port/check?host=db.example.com&port=5432&timeout=8000"

Reading the answer: open, refused, or filtered

The detail string is where the useful nuance lives. “Closed” and “filtered” are not the same failure — one means something is listening on that IP but not that port, the other usually means a firewall is silently dropping packets.

detailWhat it meansTypical cause
Port is open and accepting connectionsTCP handshake completedService is up and reachable from the public internet
Connection refused — port is closed or no service listeningHost answered, but rejected that portNothing bound to the port, or the process died
Connection timed out — port may be filtered by firewallNo answer at all within the timeoutSecurity group, iptables DROP rule, or black-holed traffic
Connection timed outSocket timeout with no error codePacket loss or a very slow path
Host unreachableNo route to the hostBad DNS target, dead network, or unroutable address

A practical pattern: if a deploy reports “service healthy” but the probe returns refused, the process never started. If it returns timed out, the process may be fine but the routing rule is wrong. That distinction resolves most “it works locally” tickets before anyone opens a terminal.

Sweep 20 common ports in one call

The second endpoint is the fast preflight. One request probes all twenty of these ports:

21 FTP · 22 SSH · 23 Telnet · 25 SMTP · 53 DNS · 80 HTTP · 110 POP3
143 IMAP · 443 HTTPS · 465 SMTPS · 587 SMTP Submission · 993 IMAPS
995 POP3S · 3306 MySQL · 3389 RDP · 5432 PostgreSQL · 6379 Redis
8080 HTTP-Alt · 8443 HTTPS-Alt · 27017 MongoDB
curl "https://agentmediatools.com/api/port/scan-common?host=example.com"
{
  "success": true,
  "host": "example.com",
  "ports_scanned": 20,
  "open_ports": 2,
  "elapsed_ms": 1870,
  "results": [
    { "port": 80, "service": "HTTP", "open": true },
    { "port": 443, "service": "HTTPS", "open": true },
    { "port": 22, "service": "SSH", "open": false }
  ]
}

Two things to know about the shape. The probes run in parallel with a fixed two-second timeout, so the sweep usually finishes in about two seconds no matter how many ports are filtered. And results is appended as each probe finishes, so the array order is completion order, not port order — sort it client-side for a tidy report. All 20 entries are returned; open_ports is just the count.

An open port is not a vulnerability and a closed port is not proof of safety. This tool only reports whether a TCP connection succeeded — banners, TLS versions, and application logic are out of scope.

Python: audit a list of hosts

The API earns its keep through repetition. This script checks one port across several hosts:

import requests

HOSTS = ["app.example.com", "api.example.com", "db.example.com"]
PORT = 443
BASE = "https://agentmediatools.com/api/port/check"

for host in HOSTS:
    r = requests.get(BASE, params={"host": host, "port": PORT}, timeout=20)
    data = r.json()
    if not data.get("success"):
        print(f"{host:24} ERROR  {data.get('error')}")
        continue
    state = "OPEN" if data["open"] else "CLOSED/FILTERED"
    print(f"{host:24} {state:15} {data['detail']} ({data['elapsed_ms']} ms)")

For a full preflight, swap in the sweep endpoint and only surface what is open:

import requests

HOST = "app.example.com"
r = requests.get(
    "https://agentmediatools.com/api/port/scan-common",
    params={"host": HOST},
    timeout=25,
)
data = r.json()
open_ports = sorted(
    (entry for entry in data.get("results", []) if entry["open"]),
    key=lambda entry: entry["port"],
)
for entry in open_ports:
    print(f"{HOST}:{entry['port']} open ({entry['service'] or 'unknown service'})")

Boundaries worth knowing

Rate limits and free quota

Port checks are free public tools, so they draw on the shared free tool allowance rather than flexible credits. As of writing:

CallerDaily allowance
Anonymous (per IP)10 successful tool calls/day
Free account25/day
Pro1,000/day
Agent key (mt_…), free25/day
Agent key, Pro1,000/day

Two details soften the daily cap. Failed requests with a 4xx status do not consume the anonymous allowance — the counter only increments after a successful response — and a separate burst limiter allows 60 requests per minute per IP, skipped entirely when you authenticate with a session or agent key. Batch many probes and that burst ceiling is what you hit first.

Check where you stand with GET /api/usage, which returns your identity type, used_today, daily_limit, and remaining. When the cap is reached the API answers HTTP 429 with a machine-readable code such as ANON_DAILY_LIMIT or AGENT_FREE_DAILY_LIMIT — handy when you want an agent to back off instead of retrying blindly.

Where this fits in an agent workflow

One note for MCP users: the port checker is REST-only — it is not exposed as an MCP tool, so agents on Claude Desktop, Hermes, or Codex should call the HTTP endpoint directly. The Agent Hub lists which features do have MCP equivalents.

Related reading

Run a port check now

Probe a host or sweep the common ports from the catalog, or read the full API docs for the rest of the network utilities.

Open the tool catalog

Tags: port checker API, free API, network utilities, TCP, curl, Python, agent automation