MCP Transport

Choose how your MCP client connects to WhaleTools — locally via stdio or remotely over HTTP+SSE.

Overview

The WhaleTools MCP server supports multiple transport modes. The Model Context Protocol defines how AI clients discover and invoke tools — the transport layer determines how those messages travel between client and server.

stdio runs a local Node.js process and communicates over stdin/stdout. This is the default for Claude Desktop and Cursor. HTTP+SSE connects to the hosted MCP server over HTTPS, ideal for web-based clients that cannot spawn local processes.

stdio Transport

The stdio transport spawns the WhaleTools MCP server as a local Node.js child process. The AI client writes JSON-RPC messages to the process's stdin and reads responses from stdout. This is the current default and provides the lowest latency.

Best for: Claude Desktop, Cursor, Claude Code, and any MCP client that can manage child processes.

Add to your claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "whaletools": {
      "command": "npx",
      "args": ["-y", "whale-code", "mcp", "--store", "your-store-id"],
      "env": {
        "WHALETOOLS_API_KEY": "your-api-key"
      }
    }
  }
}

How it works

The AI client spawns npx whale-code mcp as a child process.
Client sends JSON-RPC requests (e.g. tools/list, tools/call) to stdin.
Server processes the request and writes JSON-RPC responses to stdout.
Lifecycle is tied to the client — process exits when the client disconnects.

HTTP+SSE Transport

The HTTP+SSE transport connects to the hosted WhaleTools MCP server over HTTPS. No local Node.js installation required. This follows the Streamable HTTP protocol defined in the MCP specification (2025-03-26).

Best for: web applications, cloud-hosted agents, and environments where spawning local processes is not possible.

Endpoint

POST https://vm.whaletools.cloud/agent/mcp

Headers

Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: wt_live_...

Streamable HTTP Protocol

Per the MCP 2025-03-26 specification, the Streamable HTTP transport uses a single HTTP endpoint for all communication:

Client sends JSON-RPC requests via POST to the MCP endpoint.
Server may respond with a single JSON-RPC response or open an SSE stream for progressive results.
The server includes a Mcp-Session-Id header to maintain session state across requests.
Clients must include the session ID in subsequent requests to resume the session.
Notifications and server-initiated messages are delivered via SSE on the open stream.

Example — initialize a session:

curl -X POST https://vm.whaletools.cloud/agent/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: wt_live_..." \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0.0" }
    }
  }'

Authentication

Each transport authenticates differently, but both grant the same level of tool access.

stdio — Session File

When using stdio, the MCP server reads credentials from ~/.whaletools/session.json, created by whale login. Alternatively, set the WHALETOOLS_API_KEY environment variable in your MCP client config.

# CLI login (creates session.json)
npx whale-code login

# Or set env var directly
export WHALETOOLS_API_KEY="wt_live_..."

HTTP+SSE — API Key Header

When using the HTTP transport, pass your API key in the x-api-key header on every request. Generate keys from your API Keys dashboard.

x-api-key: wt_live_your_key_here

Tool Discovery

The WhaleTools MCP server exposes 54 tools. To keep the initial handshake fast, tool schemas are loaded lazily. The discover_tools meta-tool returns extended input schemas for any tool on demand.

How it works

On tools/list, the server returns all 54 tools with minimal schemas.
The AI client calls discover_tools with a tool name to fetch its full input schema, including all parameters and descriptions.
The client can then call the tool with the correct arguments.

Example — discover the orders tool schema:

{
  "method": "tools/call",
  "params": {
    "name": "discover_tools",
    "arguments": {
      "tool_name": "orders"
    }
  }
}

OAuth Discovery

For third-party MCP clients that support OAuth-based authentication, WhaleTools publishes standard OAuth authorization server metadata.

Metadata Endpoint

GET https://vm.whaletools.cloud/agent/.well-known/oauth-authorization-server

Returns a JSON document with the authorization endpoint, token endpoint, supported grant types, and scopes. MCP clients can use this to initiate an OAuth flow instead of requiring a pre-configured API key.

Choosing a Transport

Both transports provide access to the same 54 tools and API surface. Choose based on your client environment.

	stdio	HTTP+SSE
Connection	Local process (stdin/stdout)	HTTPS + Server-Sent Events
Best for	Desktop AI assistants	Web apps, remote clients
Authentication	Session file or env var	API key header
Local install	Node.js + npx required	None
Tool access	Full (54 tools)	Full (54 tools)
Latency	Lowest (local)	Network round-trip
Firewall	No inbound ports needed	Outbound HTTPS only