Protocol Reference - HaloAgents

Transport

Aspect	Value
Protocol	Model Context Protocol `2025-06-18` (also `2025-03-26`, `2024-11-05`)
Transport	Streamable HTTP, JSON-RPC 2.0 (single endpoint, stateless per request, no server-to-client stream)
Endpoint	`POST https://app.haloagents.ai/api/mcp`
ChatGPT plugin endpoint	`POST https://app.haloagents.ai/api/mcp/chatgpt` (same server; see below)
Auth	OAuth 2.1 with PKCE, `Authorization: Bearer halo_at_*`
Server name	`halo-agents`
Server version	`1.1.0`

Two surfaces

/api/mcp is the canonical server: the URL every client is documented against and the one listed in the Claude Connectors Directory. It is auth-first: every request without a credential, initialize included, is answered with 401 and the WWW-Authenticate challenge below. That is how Claude detects that sign-in is required when you add the connector. /api/mcp/chatgpt is the same server as the ChatGPT / Codex plugin connects to it. The only difference is that initialize, ping and tools/list answer without a credential (the full tool catalogue, each tool declaring the OAuth scopes that unlock it in securitySchemes), because OpenAI’s plugin portal scans tools before an account is linked. tools/call always requires a token. A token issued for a grant that carried an RFC 8707 resource is bound to that surface and refused on the other; grants from clients that omit resource (allowed for compatibility) are accepted on both. GET on either endpoint returns 405 (there is no SSE stream to open).

Discovery URLs

Walk the standard discovery flow:

URL	RFC	What it returns
`/.well-known/oauth-protected-resource`	RFC 9728	The resource id (`https://app.haloagents.ai/api/mcp`) and the authorization-server issuer (`https://app.haloagents.ai`) to talk to.
`/.well-known/oauth-protected-resource/api/mcp`	RFC 9728 §3.1	The same document at the path-suffixed location clients try first.
`/.well-known/oauth-protected-resource/api/mcp/chatgpt`	RFC 9728 §3.1	The document for the ChatGPT surface (`resource` is that URL).
`/.well-known/oauth-authorization-server`	RFC 8414	The full OAuth metadata: `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, `revocation_endpoint`, supported scopes, supported PKCE methods, `client_id_metadata_document_supported`, `authorization_response_iss_parameter_supported`.

A 401 from either endpoint carries a WWW-Authenticate: Bearer realm="halo-mcp", resource_metadata="...", as_uri="...", error="invalid_token" header pointing at the right documents, so a client doesn’t need to know the URLs ahead of time.

OAuth 2.1 endpoints

Endpoint	Method	RFC	Notes
`/api/mcp/oauth/register`	`POST`	RFC 7591	Dynamic Client Registration. Public; rate-limited at 10 registrations per IP per hour.
`/api/mcp/oauth/authorize`	`GET`	RFC 6749 §4.1	Authorization-code + PKCE entry point. Bounces unauthenticated users through `/signin`.
`/api/mcp/oauth/consent`	`POST`	(Halo)	Internal. The consent UI’s form posts here to issue the authorization code.
`/api/mcp/oauth/token`	`POST`	RFC 6749 §3.2	Token + refresh grants. `grant_type` must be `authorization_code` or `refresh_token`.
`/api/mcp/oauth/revoke`	`POST`	RFC 7009	Idempotent. Always returns 200.

Supported grants: authorization_code, refresh_token. Supported PKCE methods: S256 only. Supported response types: code. Supported token endpoint auth methods: none (public clients), client_secret_basic, client_secret_post. Clients identify themselves in one of two ways:

Dynamic Client Registration (RFC 7591): POST /api/mcp/oauth/register once, then use the returned client_id.
Client ID Metadata Documents: the client_id is the https URL of the client’s own metadata document (ChatGPT uses https://chatgpt.com/oauth/client.json, Claude Code https://claude.ai/oauth/claude-code-client-metadata). Halo fetches the document at /authorize, checks that it names itself and that every redirect URI is on the document’s origin (or loopback), and accepts it as a public client. No registration call is needed.

Loopback redirect URIs (http://localhost/..., http://127.0.0.1/...) match with the port ignored (RFC 8252 §7.3), so native clients can bind an ephemeral port per authorization. Every authorization response, success or error, carries iss (RFC 9207).

Token formats

Token	Prefix	Lifetime
Access token	`halo_at_`	1 hour
Refresh token	`halo_rt_`	Long-lived, rotates on every use
Authorization code	`halo_ac_`	5 minutes, single-use

All three are 256-bit random values, base64url-encoded after the prefix. Halo persists only the SHA-256 hash; on every request the bearer is hashed and looked up. There is no JWT, no signature verification, no jwks_uri.

JSON-RPC methods

`initialize`

Capabilities handshake. Required as the first call after a fresh OAuth. Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "serverInfo": { "name": "halo-agents", "title": "Halo", "version": "1.1.0" },
    "capabilities": {
      "tools": { "listChanged": false }
    }
  }
}

`ping`

Liveness check. Returns an empty object on success.

{ "jsonrpc": "2.0", "id": 2, "method": "ping" }

`tools/list`

Returns the tool descriptors the token’s scopes (and the org’s connections + agent toggles) unlock. Request:

{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "tools": [
      {
        "name": "search_docs",
        "description": "Search the public Halo Agents documentation...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "page_size": { "type": "number" }
          },
          "required": ["query"],
          "additionalProperties": false
        }
      },
      {
        "name": "linear.create_bug",
        "description": "File a bug ticket in Linear...",
        "inputSchema": { "type": "object", "properties": { "...": "..." } },
        "annotations": { "destructiveHint": true }
      }
    ]
  }
}

Tool names are namespaced as <integration>.<action> for native integrations, mcp.<slug>.<tool> for connected external MCP servers, and prefixed bare names for the built-in tool families: search_docs / read_doc (docs proxy), setup_* (setup helpers), data_* (workspace-data reads plus the data_update_user / data_update_company writes), inbox_* (ticket replies, notes, triage, outreach), automation_* (campaign read / create / edit / preview / activate), and media_* (image upload / list for email content). The annotations.destructiveHint: true flag is set on tools that mutate external state, and readOnlyHint: true on pure reads. The initialize result also carries an instructions string describing the markdown content model and the build flow, which MCP clients pass to the model as context.

`tools/call`

Invoke a tool. Wrap arguments under params.arguments; pass session metadata under params._meta. Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "hubspot.create_deal",
    "arguments": { "name": "ACME renewal", "amount": 50000 },
    "_meta": {
      "bound_end_user_id": "u_abc123"
    }
  }
}

Response (success):

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"deal_id\": \"deal_xyz\", ...}"
      }
    ],
    "isError": false
  }
}

The result is always wrapped in a single text content block. Structured tool output is JSON-stringified (with 2-space indent) inside that block.

Error codes

Standard JSON-RPC plus a couple of Halo-specific codes:

Code	Meaning
`-32700`	Parse error (invalid JSON body).
`-32600`	Invalid Request (bad JSON-RPC envelope).
`-32601`	Method not found, or unknown tool name on `tools/call`.
`-32602`	Invalid params (validation failure on tool args).
`-32603`	Internal error.
`-32001`	Unauthorized (no token, bad token, expired token). Returned with HTTP 401 + `WWW-Authenticate`.
`-32002`	Forbidden (scope denied, destructive blocked, integration disabled, agent disabled, rate limited, feature flag off).

Tool-call failures preserve the original error code where possible: unauthorized → -32002, validation → -32602, not_found → -32601, anything else → -32603.

Rate limits

Method	Per-token cap
`tools/list`	60 per minute
`tools/call`	120 per minute
Other	60 per minute

Caps are per-token, on top of the IP-based dashboard limit. Hitting one returns HTTP 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Per-action and per-org caps still apply on top. DCR is rate-limited at 10 registrations per IP per hour.

Session metadata (`_meta`)

The MCP _meta envelope on tools/call lets clients pass per-call context that isn’t part of the tool’s input schema:

Key	Value	Effect
`bound_end_user_id`	Halo customer id	The tool runs on behalf of that customer (resolved per call against your org).
`bound_email`	Email string	Same as above but resolved by email lookup. Use when the client only knows the email.

The binding is re-validated server-side on every call. A stale id, a forged id, or an id from a foreign tenant is rejected.

Helpful headers

Halo sets these on relevant responses:

Header	When
`WWW-Authenticate: Bearer realm="halo-mcp", resource_metadata="...", as_uri="..."`	On 401 responses from `/api/mcp`.
`Cache-Control: public, max-age=300`	On the `.well-known/*` discovery documents.
`Cache-Control: no-store`	On `/oauth/token` responses (per RFC 6749 §5.1).
`Retry-After`, `X-RateLimit-*`	On 429 responses.

A bare-bones client

A minimal curl walkthrough once you have an access token:

TOKEN="halo_at_..."
URL="https://app.haloagents.ai/api/mcp"

# Initialize
curl -sX POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# List tools
curl -sX POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Call a tool
curl -sX POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params": {
      "name":"search_docs",
      "arguments": {"query":"escalation policy","page_size":5}
    }
  }'

​Transport

​Two surfaces

​Discovery URLs

​OAuth 2.1 endpoints

​Token formats

​JSON-RPC methods

​initialize

​ping

​tools/list

​tools/call

​Error codes

​Rate limits

​Session metadata (_meta)

​Helpful headers

​A bare-bones client