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.
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.
| Endpoint | What it does | Key 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.
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:
open — the boolean to branch on.service — a label when the port is in the common-services table (443 → HTTPS, 3306 → MySQL, 6379 → Redis), else null.elapsed_ms — connect time, measured server-side.timeout_ms — the timeout applied, so you can tell a refusal from a probe you cut short.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"
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.
detail | What it means | Typical cause |
|---|---|---|
| Port is open and accepting connections | TCP handshake completed | Service is up and reachable from the public internet |
| Connection refused — port is closed or no service listening | Host answered, but rejected that port | Nothing bound to the port, or the process died |
| Connection timed out — port may be filtered by firewall | No answer at all within the timeout | Security group, iptables DROP rule, or black-holed traffic |
| Connection timed out | Socket timeout with no error code | Packet loss or a very slow path |
| Host unreachable | No route to the host | Bad 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.
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.
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'})")
localhost, private ranges, and link-local addresses are rejected before any connection is attempted, so you cannot probe your LAN or an internal VPC with it./api/port/check calls.{"success": false, "error": "..."} with a normal status code, so check success rather than the status line.Port checks are free public tools, so they draw on the shared free tool allowance rather than flexible credits. As of writing:
| Caller | Daily allowance |
|---|---|
| Anonymous (per IP) | 10 successful tool calls/day |
| Free account | 25/day |
| Pro | 1,000/day |
Agent key (mt_…), free | 25/day |
| Agent key, Pro | 1,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.
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.
GET /api/tools.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 catalogTags: port checker API, free API, network utilities, TCP, curl, Python, agent automation