moonlight-lupin/agent-skills/endpoint-probe

Endpoint Probe

Probe a base URL to discover its API surface: type, auth, endpoints, rate limits, CORS, and server fingerprint.

When to Use

• User gives you a base URL and asks "what API is available?" or "what endpoints does this have?"
• You need to understand an undocumented or partially-documented API before building an integration
• User asks "how does this API authenticate?" or "what auth does this endpoint need?"
• You're evaluating a third-party service and need to map its API surface
• User says "discover", "probe", "explore", or "recon" an API endpoint
• User wants to know what tools an MCP server provides before configuring it
• User asks "what does this MCP server offer?" or "what tools does MCP server X have?"

Don't use for:

• Scraping HTML page content (use website-scraping)
• QA testing of known functionality (use a QA/testing skill)
• Configuring MCP servers (use an MCP configuration skill) — this skill discovers MCP server surfaces, it doesn't configure them
• Monitoring an API over time (this is a one-shot discovery tool)

Workflow

1. Run the probe script

python scripts/probe_api.py <base_url> [options]

Options:

Examples:

# Basic probe — no auth
python scripts/probe_api.py https://api.example.com
 
# With Bearer token
python scripts/probe_api.py https://api.example.com --auth "tok_abc123"
 
# With API key (sends X-API-Key header)
python scripts/probe_api.py https://api.example.com --auth "key_xyz" --auth-type apikey
 
# Skip resource guessing (faster, less noisy)
python scripts/probe_api.py https://api.example.com --no-guess
 
# JSON output for programmatic use
python scripts/probe_api.py https://api.example.com --json

2. Interpret the report

The probe runs 7 phases in sequence:

1. Server fingerprint — identifies framework (Express, FastAPI, Django, Rails, Spring, etc.) from Server and X-Powered-By headers
2. Well-known paths — checks ~40 discovery paths: /openapi.json, /swagger.json, /docs, /graphql, /.well-known/, /health, /version, etc.
3. GraphQL introspection — POSTs an introspection query to /graphql, /api/graphql, /query and extracts types if successful
4. OPTIONS / CORS — sends OPTIONS to /, /api, /api/v1 to discover allowed methods and CORS policy
5. Auth detection — hits likely-protected endpoints without credentials, examines 401/403 responses and WWW-Authenticate headers
6. Rate limits — checks for X-RateLimit-*, RateLimit-*, Retry-After headers
7. REST resource guessing — probes ~50 common resource paths (/api/users, /api/orders, etc.) and reports non-404 responses

3. Use the findings

• OpenAPI found → parse the spec for full endpoint list, request/response schemas, auth schemes. The probe already extracts endpoints from the spec.
• GraphQL introspection works → you have the full type system. Build queries from the discovered types.
• Only REST resources found → the API is undocumented. Use the discovered resource paths as a starting point and probe individual endpoints with GET/POST/PUT/DELETE.
• Auth detected → use the identified scheme for all subsequent requests.
• Nothing found → the API may be behind a login, use non-standard paths, or not exist at that URL. Try with auth credentials, or check if the base URL is correct.

MCP Server Probing

The probe also supports discovering MCP (Model Context Protocol) server surfaces — tools, resources, and prompts with full input schemas. This lets you evaluate an MCP server before configuring it in Hermes.

MCP over HTTP (StreamableHTTP transport)

# Probe a remote MCP server
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp
 
# With auth headers
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp --auth "tok_abc123"
 
# With custom headers
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp --header "X-API-Key: mykey"

MCP over stdio (local subprocess)

# Probe a local MCP server (npx-based)
python scripts/probe_api.py "npx -y @modelcontextprotocol/server-time" --mcp-stdio
 
# Probe a Python-based MCP server
python scripts/probe_api.py "python3 /path/to/mcp_server.py" --mcp-stdio
 
# With environment variables
python scripts/probe_api.py "npx -y @modelcontextprotocol/server-github" --mcp-stdio \
  --mcp-env "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx"

What the MCP probe discovers

The probe performs the full MCP handshake sequence:

1. Initialize — JSON-RPC initialize with protocol version, client info, and capabilities. Reports server name, version, protocol version, and server capabilities.
2. Tools — tools/list → all tool names, descriptions, and full input schemas (parameter names, types, required/optional, defaults, enums)
3. Resources — resources/list → all resource URIs, names, descriptions, and MIME types
4. Prompts — prompts/list → all prompt template names, descriptions, and arguments

MCP vs an MCP configuration skill

Workflow: Use endpoint-probe --mcp to evaluate a server → decide if useful → use an MCP configuration skill to register it → restart the agent.

Common Pitfalls

1. Base URL wrong or too specific. https://api.example.com is correct; https://api.example.com/v1/users/123 is too specific — the probe needs the root to discover paths. Strip trailing paths.

OpenAI-compatible APIs: If the base URL is an inference endpoint like https://provider.ai/v1 or https://provider.ai/zen/go/v1, the probe will find nothing because discovery paths (/openapi.json, /docs, etc.) are served from the domain root, not the inference prefix. Always probe the domain root (https://provider.ai) to find the OpenAPI spec and full API surface. The inference endpoints (/v1/chat/completions, /v1/models) are usually a small slice of a larger platform API.

1. GraphQL introspection disabled. Many production GraphQL APIs disable introspection for security. The probe will show status 200/400/403 with "introspection disabled" — this confirms GraphQL exists but the schema is hidden. Try sending a simple query like {"query": "{ __typename }"} to confirm.

1. Auth-gated APIs return 404 instead of 401. Some APIs return 404 for unauthenticated requests to hide endpoint existence. If everything is 404, try providing --auth credentials.

1. Rate limiting during probe. The script makes ~80-100 requests concurrently (8 threads). Most APIs tolerate this, but if you hit 429s, increase --timeout or use --no-guess to reduce request count. The script auto-detects rate-limit exhaustion (via X-RateLimit-Remaining: 0) and skips resource guessing to avoid false positives — check the report for rate_limited_skipped_guessing: true.

1. Uniform 403 ≠ auth-gated. If every discovery path returns 403 with the same error body, you're rate-limited, not auth-blocked. Check rate-limit headers (X-RateLimit-Remaining) before interpreting 403s as auth requirements. A true auth-gated API returns 401 (with WWW-Authenticate) or mixed 200/401/403 across paths, not uniform 403.

1. 403 on `/graphql` means the endpoint exists. A 403 on /graphql confirms the endpoint is there but introspection is blocked — not that GraphQL is absent. A 404 means the endpoint doesn't exist. Don't conflate the two.

1. CORS headers only on OPTIONS. Some APIs only send CORS headers on OPTIONS preflight, not on GET. The probe checks OPTIONS separately for this reason.

1. False positives on /health, /status. These paths may return 200 from a load balancer or CDN even if the API itself is down. Treat them as "something is listening" not "API is healthy".

1. Server fingerprint unreliable. X-Powered-By is often stripped by proxies. The framework hints are best-effort — don't treat them as definitive.

1. Self-signed certs. The script uses urllib which verifies certs by default. PYTHONHTTPSVERIFY=0 does NOT affect urllib (it only affects requests/httpx). Self-signed targets are currently unsupported — use --allow-private for internal hosts but self-signed TLS requires a future --insecure flag with a custom ssl.SSLContext.

1. Concurrency is load-bearing. The probe script uses concurrent.futures.ThreadPoolExecutor(max_workers=8) for both well-known paths and resource guessing. Sequential probing of ~90 paths times out against slow APIs (>120s). If you modify the script, preserve the thread pool — do not revert to sequential requests.

1. SPA catch-all false positives. Next.js, Nuxt, and other SPA frameworks serve the same HTML page (200 + text/html) for every path — including /api/users, /health, /openapi.json, etc. This floods the report with bogus "endpoints" that are just the SPA shell. The script auto-detects this in REST resource guessing (uniform 200 + text/html + similar body lengths → discarded) and guards SOAP detection (WSDL path returning text/html is not SOAP). However, the discovery-paths phase may still show many html-docs entries — these are SPA routes, not real API docs. If the server fingerprint shows Next.js/Nuxt and most discovery paths return 200 text/html, treat all but the OpenAPI spec (if found) as SPA noise.

1. MCP stdio server hangs. Some MCP servers don't exit cleanly on stdin close. The probe sends terminate() then waits 5s before kill(). If a server ignores SIGTERM, the probe may take 5s longer. This is expected — the probe always cleans up.

1. Reports redact credential values, not auth protocol. Auth detection still surfaces scheme (Bearer, Basic, WWW-Authenticate, “API key required”, cookie names). Echoed Authorization / X-API-Key values, Set-Cookie values, and token-shaped strings in error bodies are replaced with *** so reports/logs stay shareable. If a header looks “empty” of secrets, check for *** — that means a secret was present and scrubbed.

1. MCP protocol version mismatch. The probe sends protocol version 2025-06-18. Older MCP servers may use 2024-11-05 — the server negotiates and returns its supported version in the response. The probe reports the negotiated version in the summary. If initialize fails with a protocol error, the server may require an older version.

1. MCP HTTP endpoint URL. MCP over HTTP uses a single endpoint URL (e.g. https://mcp.example.com/mcp), not path-based routing. All JSON-RPC requests go to the same URL via POST. Don't append /tools/list or similar — the --mcp flag handles this correctly.