MCP server

Helmcode exposes a remote MCP (Model Context Protocol) server so you can use our tools directly inside MCP-compatible agents and editors — authenticated with the same API key you already use for the REST API.

MCP is a different protocol from our REST endpoints. Instead of calling POST /v1/... paths, an MCP client talks JSON-RPC to a single endpoint and discovers the tools available to your account.

Endpoint

https://api.helmcode.com/mcp

Transport: Streamable HTTP (remote), stateless — no session to keep alive.
Auth: Authorization: Bearer sk-your-key-here — the same sk-hke_ key from your Dashboard.
An unauthenticated or invalid request returns 401 Unauthorized.

Protocol

The server speaks JSON-RPC 2.0. The methods you’ll use:

Method	Purpose
`initialize`	Handshake — negotiate protocol version and capabilities
`tools/list`	List the tools enabled for your account
`tools/call`	Invoke a tool with arguments
`ping`	Liveness check

Tools

The server is a growing tool registry — more tools will be added over time. Availability is per account: a tool appears in tools/list only when it’s enabled for your organization.

`web_search`

Runs a web search and returns ranked results. Same arguments as the REST POST /v1/search endpoint:

Argument	Type	Default	Notes
`query`	string	—	The search query (required)
`count`	integer	`5`	Number of results, 1–20
`freshness`	string	—	`pd`, `pw`, `pm`, `py`, or a `YYYY-MM-DDtoYYYY-MM-DD` range
`fetch_content`	boolean	`false`	Fetch and return page content for each result

Limits

MCP calls share the same budget as the REST API — one per-key rate limit, daily quota, and concurrency cap across both surfaces. A search made over MCP counts exactly like the same search made against POST /v1/search. See Rate limits.

Connect in an MCP client

1. Native remote (url + headers)

Clients that support remote MCP servers take a URL and headers directly:

{
  "mcpServers": {
    "helmcode": {
      "url": "https://api.helmcode.com/mcp",
      "headers": { "Authorization": "Bearer sk-your-key-here" }
    }
  }
}

2. stdio-only clients via `mcp-remote`

If your client only speaks stdio, bridge to the remote server with mcp-remote:

{
  "mcpServers": {
    "helmcode": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.helmcode.com/mcp",
        "--header",
        "Authorization:Bearer sk-your-key-here"
      ]
    }
  }
}

Tip: keep the server entry name short (e.g. helmcode). Many clients prefix each tool with the server name, so helmcode surfaces the tool as helmcode_web_search. A verbose name like helmcode-web-search would produce a duplicated-looking helmcode_web_search_web_search.

Raw JSON-RPC example

You can call the server directly with curl. This invokes web_search via tools/call:

curl https://api.helmcode.com/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "web_search",
      "arguments": { "query": "eu ai infrastructure", "count": 5 }
    }
  }'

To discover what’s enabled for your account, call tools/list the same way:

curl https://api.helmcode.com/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'