MCP SSE transport — /mcp/sse and /mcp/messages

Connect AI agents to the Solana AI Gateway via Model Context Protocol SSE transport for real-time tool invocation.

The Solana AI Gateway implements the Model Context Protocol (MCP) using Server-Sent Events (SSE). Clients such as Claude Desktop and Cursor can connect to the SSE endpoint to discover and invoke gateway tools in real time. After establishing the SSE stream, the client sends JSON-RPC messages via POST to the messages endpoint using the session ID returned in the stream.

Endpoints

Establish SSE stream

GET /mcp/sse

No authentication required.

The gateway opens a long-lived SSE connection and assigns a unique sessionId. The first event contains the messages URL, for example /mcp/messages?sessionId=<uuid>.

Send messages

POST /mcp/messages?sessionId=<uuid>
Content-Type: application/json

Send JSON-RPC tool invocation requests to this endpoint using the sessionId from the SSE stream.

How it works

1. Open SSE connection

   Send GET /mcp/sse. The gateway creates a session and streams events back to your client.

2. Read session ID

   The gateway emits the messages endpoint URL with a unique sessionId query parameter.

3. POST tool requests

   Send JSON-RPC tools/call requests to POST /mcp/messages?sessionId=<uuid>.

4. Receive responses

   Results are streamed back over the original SSE connection as JSON-RPC responses.

Available MCP tools

The gateway exposes the following tools over MCP. Each tool accepts the same parameters as the equivalent REST endpoint and returns structured JSON text content.

Tool name	Purpose
get_solana_balance	Fetch native SOL balance with network selection.
get_solana_blockhash	Get the latest finalized blockhash.
get_token_accounts	Scan all SPL token holdings for a wallet.
get_recent_transactions	Retrieve recent transaction signatures.
simulate_solana_transaction	Simulate a base64 transaction before broadcast.
find_ata	Derive the Associated Token Account for a wallet and mint.
token_profile	Get token metadata, decimals, and security/honeypot flags.
optimal_fee	Get tiered priority fee recommendations.
decode_tx	Translate raw transaction logs into human-readable summaries.

Example: cURL SSE connection

Open SSE stream

curl -N "$GATEWAY_URL/mcp/sse"

Example: TypeScript SSE client

TypeScript

const eventSource = new EventSource(`${process.env.GATEWAY_URL}/mcp/sse`);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("SSE event:", data);
};

// After reading the sessionId from the first SSE event:
async function callTool(sessionId: string) {
  const res = await fetch(
    `${process.env.GATEWAY_URL}/mcp/messages?sessionId=${sessionId}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: 1,
        method: "tools/call",
        params: {
          name: "get_solana_balance",
          arguments: {
            wallet: "Brpc8HoPo1d3Uiyo7kbERnjMqwLJJmbWxtwxHxzar6DU",
            network: "mainnet-beta",
          },
        },
      }),
    }
  );
  return await res.json();
}

Errors

Status	Meaning
400	Missing sessionId on POST /mcp/messages.
404	MCP SSE Session not found — the session ID is invalid or expired.

Notes

• SSE sessions are cleaned up automatically when the client disconnects.
• The gateway applies the same rate limits to MCP traffic as to REST traffic.
• For tool schemas and descriptions, fetch the MCP manifest first.