Binary³ MCP integration guide.

Binary³ MCP is an access layer that exposes selected Binary³ security capabilities to MCP-compatible clients over the Model Context Protocol. It is the interface to the scanners — not itself a scanner, an enforcement engine, or a policy gate — and it operates independently of Axon, which is a separate Binary³ capability and is not required to discover or invoke MCP tools.

• Machine endpoint https://mcp.binarycubed.com/mcp (MCP protocol surface; not a web page)
• Transport Streamable HTTP, stateless, JSON responses
• Authentication Bearer credential on every protocol request
• Tools keysweep_scan_text and microdefend_scan_website — the complete current inventory

Catalog reference: /mcp/tools — the canonical tool catalog. This page is the integration guide; deeper architecture detail lives at /mcp/security.

Getting started

1. Step 1 — Identify a compatible MCP client. The client must support remote MCP servers over the streamable HTTP transport and a per-request bearer Authorization header.
2. Step 2 — Configure the Binary³ MCP endpoint. Use https://mcp.binarycubed.com/mcp exactly. The configuration shape is shown in Client configuration.
3. Step 3 — Configure authentication. Obtain a bearer credential from the RQE developer portal (live credentials require a paid RQE plan) and present it as Authorization: Bearer <BINARY3_MCP_API_KEY> on every request.
4. Step 4 — Connect. The client opens the protocol session against the machine endpoint. The current protocol revision is served natively; clients on the previous revision complete the legacy initialize handshake instead.
5. Step 5 — Discover available tools. Issue tools/list; see Tool discovery.
6. Step 6 — Invoke a tool. Issue tools/call with the tool name and its arguments; see the per-tool sections below.
7. Step 7 — Process the structured result. Read the structured content and check the error flag before using values; see Responses.

Steps 3–7 assume an issued credential. The public key surface used to verify credentials is qualified, and authenticated end-to-end invocation is independently qualified (post-roadmap production gate, 2026-09-14) — see Qualification status.

Endpoint

Two different surfaces share the /mcp path and are not interchangeable:

• Protocol revision 2026-07-28 served natively; 2025-03-26 clients are answered through the legacy initialize handshake
• State Stateless: every request carries its own credential; no server-side protocol session or event stream is required
• Responses Plain JSON (no SSE framing on responses)
• Path discipline /mcp is the only authenticated protocol path; the machine host also serves its public protected-resource metadata document at /.well-known/oauth-protected-resource; any other path returns 404
• Request envelope Requests on the current protocol revision must carry params._meta with both io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities; a request missing them fails with HTTP 400 and a -32602 JSON-RPC error. The legacy 2025-03-26 initialize handshake is answered without them
• Request ceiling Bodies larger than 4 MiB are refused with HTTP 413

Authentication

Every MCP protocol request carries an issued bearer credential in the HTTP Authorization header — one token, no extra whitespace. Binary³ validates the credential signature against its public JWKS, then validates issuer, audience, lifetime, credential identity, tenant binding, and the requested tool entitlement.

• Public keys https://binarycubed.com/.well-known/mcp-jwks.json — public verification keys only, served with Cache-Control: no-store
• Missing credential HTTP 401 with a WWW-Authenticate challenge identifying the realm and the protected-resource metadata document
• Rejected credential HTTP 401 with error="invalid_token" added to the challenge
• Accepted algorithms RS256 and ES256 only

Never place a credential in source control, a public document, or client-side browser code. All examples on this page use the placeholder <BINARY3_MCP_API_KEY>.

The public JWKS surface is qualified, and authenticated MCP end-to-end operation is independently qualified (2026-09-14 gate). Bearer-only REST API authentication and MCP billing remain separate qualification tracks.

Tool discovery

Discovery is protocol-native: after connecting, a client issues tools/list and receives the currently registered tools with their names, descriptions, and input schemas. No out-of-band action is required.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The response lists exactly the two registered tools, with the input schemas as served (description fields omitted from this listing):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "keysweep_scan_text",
        "inputSchema": {
          "type": "object",
          "title": "keysweep_scan_textArguments",
          "properties": { "text": { "type": "string", "title": "Text" } },
          "required": ["text"]
        }
      },
      {
        "name": "microdefend_scan_website",
        "inputSchema": {
          "type": "object",
          "title": "microdefend_scan_websiteArguments",
          "properties": { "url": { "type": "string", "title": "Url" } },
          "required": ["url"]
        }
      }
    ]
  }
}

Each entry also carries the registry description quoted verbatim in the tool sections below. The documented set always equals the registered set; the catalog at /mcp/tools is the canonical overview.

keysweep_scan_text

Registry description: "Scan supplied text for exposed secrets (API keys, tokens, private keys, credentials, database URLs). Pure analysis — no network access. Returns redacted findings: secret values are never echoed, only type/severity/confidence/fingerprint/length."

• Backing capability Binary³ KeySweep secret scanning
• Operation type Synchronous analysis of supplied text; no network access; consumes one scan quota unit per call
• Example use Check a configuration file or source snippet for exposed credentials before committing or sending it

Parameters

Response structure

Detected secret values are never returned — only type, severity, confidence, a fingerprint, and the value length. Severity is one of critical, high, medium, low.

Errors

Common errors: invalid_text (empty or non-string input), text_too_large (over 256000 characters), quota_unavailable, rate_limit_exceeded (scan quota exhausted), scan_failed, plus the shared authentication errors. The complete tool-level inventory is in Errors.

Example invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "keysweep_scan_text",
    "arguments": { "text": "<TEXT TO INSPECT>" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Qualification note: the tool contract above is verified against the registered implementation, and authenticated end-to-end invocation is qualified (2026-09-14 gate).

microdefend_scan_website

Registry description: "Run a MicroDefend website security scan (TLS posture, security headers, metadata, exposed-path audit) against a public URL. Every fetch is SSRF-defended: targets are validated and IP-pinned before any connection, redirects are re-validated per hop, response bodies are size-capped. Private/internal targets are rejected BEFORE any connection to the target is made."

• Backing capability Binary³ MicroDefend website security scanning
• Operation type Network scan of a public URL you are authorized to scan; consumes one scan quota unit per call
• Example use Check the TLS posture and security headers of a site you operate before a release

Parameters

Target validation and network behavior

Targets are validated before any connection to the target is made: private, loopback, link-local, reserved, multicast, and cloud-metadata addresses are rejected, as are internal hostname suffixes; DNS is resolved during validation, every resolved address must pass, and the answers are pinned for the fetch. Redirects are re-validated per hop (at most 3), HTTP fetches carry a 15-second connect/read timeout (DNS resolution during validation has no application-level timeout), and response bodies are capped at 2 MiB. Within a scan, checks run through a bounded worker pool and path probes run inside the API-exposure check; the concurrency slot's 180-second TTL is an abandonment bound for the ledger, not a scan runtime limit.

Response structure

Errors

Common errors: invalid_target, blocked_hostname, and blocked_ip (target fails validation, including private or internal destinations), binding_check_unavailable, db_scope_unavailable, scan_failed, plus the shared authentication errors. The complete tool-level inventory is in Errors.

Example invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "microdefend_scan_website",
    "arguments": { "url": "https://example.com" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Qualification note: the target-validation behavior above is verified against the implementation, and authenticated end-to-end invocation is qualified (2026-09-14 gate).

Responses

A successful tools/call returns a result whose structuredContent carries the tool's output object and whose content carries a text rendering. Tool-level failures are returned in the same envelope with isError set and a code: message string in the text content — they are not transport HTTP errors.

Example — keysweep_scan_text result (abridged: the content text rendering is omitted; the structured field set is contractual, values are illustrative):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": "completed",
      "risk_level": "high",
      "confidence_score": 0.9,
      "summary": { "total": 1, "by_severity": { "high": 1 }, "by_type": { "aws_access_key": 1 } },
      "detections": [
        { "type": "aws_access_key", "severity": "high", "confidence": 0.9,
          "fingerprint": "<FINGERPRINT>", "value_length": 40 }
      ],
      "text_length": 512
    },
    "isError": false
  }
}

Example — microdefend_scan_website result (abridged):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "status": "completed",
      "scan_id": "<SCAN_ID>",
      "findings": [],
      "result": {}
    },
    "isError": false
  }
}

Example — tool-level error (quota exhausted):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "rate_limit_exceeded: Scan quota exhausted for this credential." }
    ],
    "isError": true
  }
}

Errors

Transport-level (HTTP)

Tool-level (in the result envelope)

• unauthenticated: missing transport identity / unauthenticated: missing tenant binding: the request reached a tool without authenticated identity, or the credential's tenant binding could not be established.
• forbidden: credential lacks the <tool> entitlement: the credential is valid but not entitled to the requested tool.
• invalid_text / text_too_large: the KeySweep input does not meet the tool contract.
• invalid_target / url_too_long / invalid_scheme / credentials_in_url / blocked_hostname / blocked_port / blocked_ip / dns_resolution_failed: the MicroDefend target failed validation — private, internal, unresolvable, or otherwise disallowed destinations.
• rate_limit_exceeded / rate_limit_unavailable / quota_exceeded / quota_unavailable: the credential's rate window is exhausted (rate_limit_exceeded), the monthly allowance is exhausted (quota_exceeded), or a quota control could not be evaluated and execution failed closed.
• duplicate_scan / too_many_concurrent_scans / scanner_busy / scan_slots_unavailable: concurrency controls rejected the scan, or the slot ledger could not be verified and execution failed closed.
• db_scope_unavailable / db_role_unavailable / binding_check_unavailable / credential_binding_failed / target_check_unavailable: an authorization control could not be verified, so execution failed closed.
• scan_failed: the downstream security scan did not complete successfully.

Retry only transient availability errors, honoring Retry-After on 429. Changing or bypassing authentication is not a recovery path. The repository defines no custom JSON-RPC numeric error codes; malformed or unsupported protocol messages receive the SDK's standard JSON-RPC errors.

Client configuration

Configuration shape for a compatible MCP client:

{
  "mcpServers": {
    "binary3": {
      "type": "http",
      "url": "https://mcp.binarycubed.com/mcp",
      "headers": {
        "Authorization": "Bearer <BINARY3_MCP_API_KEY>"
      }
    }
  }
}

For direct protocol work (tests, custom clients), the exercised request envelope is:

POST /mcp HTTP/1.1
Host: mcp.binarycubed.com
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
MCP-Method: tools/call
Authorization: Bearer <BINARY3_MCP_API_KEY>

Troubleshooting

• The endpoint returns an HTML page: you are on the human surface (www.binarycubed.com/mcp). Point the client at the machine endpoint mcp.binarycubed.com/mcp.
• 404 on the machine host: the path must be exactly /mcp; other paths return 404 even with a valid credential.
• 401 on every request: confirm the header is exactly Authorization: Bearer <credential> — one token, no extra whitespace — and that the credential is current. A presented-but-rejected credential adds error="invalid_token" to the challenge.
• 403 origin_not_allowed: the client is sending an Origin header the endpoint does not accept; non-browser clients normally send none.
• 429 with Retry-After: the transport rate limit (120 requests per 60 seconds by default) is exhausted; wait for the indicated window.
• 413 request_too_large: the request body exceeded 4 MiB; send smaller payloads.
• 400 with a -32602 JSON-RPC error: the request is missing the required params._meta envelope keys (io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities).
• 400 with a -32022 JSON-RPC error: the declared protocol revision is not served; use 2026-07-28 (or a 2025-03-26 legacy initialize).
• Tool not discovered: call tools/list on the machine endpoint after connecting; the registered set is exactly the two tools documented here.
• forbidden on one tool only: your credential is valid but not entitled to that tool; request the entitlement rather than retrying.
• invalid_target, blocked_hostname, or blocked_ip: the scan URL points at a private, internal, or otherwise disallowed destination (the full validation-failure set is in Errors); only public http/https URLs on ports 80/443 are accepted.
• invalid_text / text_too_large: supply non-empty text of at most 256000 characters.
• rate_limit_exceeded: the scan quota is exhausted; wait for the next quota window or contact Binary³.
• quota_unavailable / binding_check_unavailable / db_scope_unavailable: an authorization control could not be verified and execution failed closed; retry later, and contact Binary³ if it persists.

Qualification status

Axon is a separate Binary³ capability: it is not a prerequisite, middleware layer, authentication layer, or enforcement dependency for Binary³ MCP, and no MCP flow on this page passes through it.

Security

Summary of the boundaries developers interact with; deeper architecture and rationale live at /mcp/security.

• Every protocol request is authenticated and authorized per tool; identity reaches tool handlers only through the authenticated scope, never from client headers.
• Scan targets are validated and IP-pinned before any connection; private and internal destinations are rejected first, redirects are re-validated per hop, and response bodies are size-capped.
• Secret values detected by KeySweep are never returned — findings carry only type, severity, confidence, fingerprint, and length.
• Scan quotas apply per credential and are consumed once per scan; transport rate limiting fails closed.
• Requests and responses carry an X-Correlation-ID: supply one to trace a request, or the endpoint mints one.