MCP#

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

textexample

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:

textexample

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#

textexample

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:

textexample

https://api.hightop.com/mcp

Headers#

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

After initialize:

textexample

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

Accept requirements:

textexample

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.

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:

jsonexample

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

Idempotency#

For mutating tools that require idempotency, MCP accepts an optional idempotency_key.

If omitted, Hightop synthesizes:

textexample

mcp:<sessionId>:<jsonrpc-id>:<toolName>

Reusing a JSON-RPC id with a different payload can still trigger idempotency_key_reuse_mismatch.

Streaming#

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

textexample

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.

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.