MCP#

Hightop exposes the Agent API over the Model Context Protocol at:

text

example

https://api.hightop.com/mcp

MCP wraps the same /v1/agent/* capability surface in JSON-RPC 2.0 tools and server-sent notifications.

Connect with Claude Desktop#

In Claude Desktop, add a connector and paste:

text

example

https://api.hightop.com/mcp

Claude opens a browser. The user completes Hightop OAuth, selects a Hightop agent, approves scopes, and returns connected.

Other MCP-compatible clients can connect to the same URL when they support Streamable HTTP, OAuth, JSON-RPC 2.0, and SSE.

Transport#

text

example

POST   /mcp   JSON-RPC 2.0 requests
GET    /mcp   Server-Sent Events stream
DELETE /mcp   Close the current session

The OAuth token must be bound to:

text

example

https://api.hightop.com/mcp

Headers#

Initialize uses POST /mcp without Mcp-Session-Id.

After initialize:

text

example

Authorization: Bearer <jwt>
Mcp-Session-Id: <session id>
Mcp-Protocol-Version: <server protocol version>

Accept requirements:

text

example

POST Accept: application/json, text/event-stream
GET  Accept: text/event-stream

Last-Event-ID is optional and only applies to GET /mcp reconnects.

Tool Surface#

tools/list returns generated tools for public /v1/agent/* catalog routes, plus inline MCP tools.

Generated tools mirror Agent API auth, scopes, rate limits, idempotency, validation, and errors. For the complete list of generated tools with their input schemas and required scopes, see the MCP Tool Reference.

Each generated tool carries the OAuth scope of the route it wraps. There is no separate mcp scope: an OAuth token must be issued for the /mcp resource (audience-bound) and carry the per-route agent:* scopes — read tools require agent:read, and each mutating tool requires its route's write scope (for example agent:payments:write). See OAuth for the scope catalog. Header-key auth (native and server-to-server clients) is scoped to the agent's full permissions.

Inline tools:

Tool	Purpose
`mcp_subscribe`	Subscribe the session to Agent API webhook event types
`mcp_unsubscribe`	Stop delivering events on the session
`agent_operations_wait_for_status`	Poll an operation until it reaches a terminal status or timeout

Wait tool input:

json

example

{
  "operation_id": "00000000-0000-0000-0000-000000000000",
  "terminal_statuses": ["executed", "execution_failed", "policy_rejected", "cancelled"],
  "timeout_seconds": 60
}

Idempotency#

Mutating tools that require idempotency expose a required idempotency_key input. Generate a fresh UUID for each logical operation.

Retrying with the same key and the same payload replays the original response.
Reusing a key with a different payload returns idempotency_key_reuse_mismatch.
Omitting the key, or sending it blank, returns validation_failed. Hightop does not synthesize a key on your behalf.

Read-only tools, and mutating tools that do not require idempotency, do not expose the field.

Streaming#

GET /mcp streams JSON-RPC notifications over SSE. Webhook events use:

text

example

notifications/hightop/agent_webhook

Delivery is at least once. Clients should dedupe by params.event.id.

Only one active SSE stream is allowed per session. A second GET /mcp displaces the prior stream.

The default active session cap is 2 sessions per agent. Cap saturation returns 429 with Retry-After.

Origin and CSRF#

Browser-origin requests must send an allowed Origin. Hightop validates origin and host before auth or database work.

Native and server-to-server clients without an Origin header are allowed when they present valid agent auth.

Troubleshooting#

Symptom	Cause	Fix
`401` on initialize	Missing or wrong auth, or token not bound to the MCP resource	Bind the OAuth token to `https://api.hightop.com/mcp`, or send valid header-key auth
`insufficient_scope` on a tool call	Token isn't bound to the `/mcp` resource, or lacks the tool's per-route `agent:*` scope	Re-consent for the `/mcp` resource with the needed scopes (OAuth)
`validation_failed` on a mutating tool	Missing or blank `idempotency_key`	Supply a fresh `idempotency_key`; Hightop does not synthesize one
`429` with `Retry-After`	Session cap saturated (default 2 per agent) or rate limit hit	Close idle sessions with `DELETE /mcp`, then retry after the delay
Missing webhook events	Not subscribed, or client ignores unknown notifications	Call `mcp_subscribe`, and poll with `agent_operations_wait_for_status` if the client drops unknown notifications
Browser request rejected before auth	Disallowed `Origin`	Use an allowed origin, or a native/server client without an `Origin` header and valid agent auth

V1 Limitations#

Webhook deliveries use the Hightop-namespaced notification method above.
Strict generic MCP clients that ignore unknown notifications should use agent_operations_wait_for_status.
Claude directory listing is not the target for v1; use custom connector install.
MCP elicitation is not implemented.
MCP resources are not advertised.
Long-running tool progress and cancellation are not implemented.