Getting started

The fastest start is to add protogrid to the agent you already use. It is an MCP server at https://api.protogrid.dev/mcp (streamable HTTP, no sign-up, no key), so your agent can then find and connect other MCP servers by itself.

Connect protogrid to your agent

Claude Code

claude mcp add --transport http -s user protogrid https://api.protogrid.dev/mcp

-s user makes it available in every project; leave it out to add it to the current project only. Run /mcp inside Claude Code to check that it is connected.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.protogrid]
url = "https://api.protogrid.dev/mcp"

OpenCode

Add to ~/.config/opencode/opencode.json (or an opencode.json in the project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "protogrid": { "type": "remote", "url": "https://api.protogrid.dev/mcp", "enabled": true }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in the project):

{ "mcpServers": { "protogrid": { "url": "https://api.protogrid.dev/mcp" } } }

VS Code

Add to .vscode/mcp.json:

{ "servers": { "protogrid": { "type": "http", "url": "https://api.protogrid.dev/mcp" } } }

Any other client

Most clients read an mcpServers block:

{ "mcpServers": { "protogrid": { "type": "http", "url": "https://api.protogrid.dev/mcp" } } }

No key is needed. A free API key raises the limits from 20 to 60 requests per minute; add it as an X-API-Key header in any of the setups above.

Try it

Ask your agent something like “use protogrid to find a server that can send an email, and tell me how to connect it”. It calls search, then get_server or get_connection, and answers with a connection block for the client you use.

Or call it over REST

The same flow is three HTTP calls.

1. Search by intent

curl -s 'https://api.protogrid.dev/v1/search?q=get+the+weather+for+a+city&class=R0,R1&limit=3'

{
  "query": "get the weather for a city",
  "mode": "hybrid",
  "count": 3,
  "results": [
    {
      "name": "io.github.Lulu-The-Narwhal/weather-mcp",
      "connection_class": "R0",
      "autonomous": true,
      "human_steps": [],
      "trust_score": 87,
      "tool_count": 2,
      "matched_tools": [{ "name": "get_weather", "description": "Current weather for a city" }]
    }
  ],
  "next_actions": [
    { "action": "get_connection", "href": "/v1/servers/{name}/connection?target=mcpServers", "arguments": { "name": "{name}", "target": "mcpServers" } }
  ]
}

class=R0,R1 keeps only servers an agent can reach on its own. See connection classes.

2. Get the connection block

curl -s 'https://api.protogrid.dev/v1/servers/io.github.Lulu-The-Narwhal%2Fweather-mcp/connection'

{
  "server": "io.github.Lulu-The-Narwhal/weather-mcp",
  "key": "weather-mcp",
  "kind": "remote",
  "class": "R0",
  "autonomous": true,
  "human_steps": [],
  "target": "mcpServers",
  "connection": { "mcpServers": { "weather-mcp": { "type": "http", "url": "https://…/mcp" } } },
  "secrets": []
}

For an R1 server the block contains a placeholder and secrets names it:

{
  "connection": { "mcpServers": { "agentdm": { "type": "http", "url": "https://api.agentdm.ai/mcp/v1/grid", "headers": { "Authorization": "${AGENTDM_TOKEN}" } } } },
  "secrets": [{ "name": "AGENTDM_TOKEN", "where": "header:Authorization" }]
}

Fill ${AGENTDM_TOKEN} from your own store. The registry never accepts secret values.

3. Connect

Use any MCP client with the block. With the TypeScript SDK the three steps are one call:

import { createClient, createTransport, findConnectable } from "@protogrid/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const registry = createClient({ baseUrl: "https://api.protogrid.dev" });
const found = await findConnectable(registry, { q: "get the weather for a city" }, { secrets: process.env });
const mcp = new Client({ name: "my-agent", version: "1.0.0" });
await mcp.connect(await createTransport(found!.connection, process.env));
const { tools } = await mcp.listTools();

See the TypeScript SDK page.

The same over MCP

Once protogrid is added to your client (above), your agent has the same flow as tools. The tools are search, get_server, list_tools, get_connection with the same arguments and results as the REST routes. See the MCP server page.

For coding agents and IDEs

get_connection formats the block for a client with ?target=: claude-code-cli, codex-toml, opencode (with {env:NAME} references), cursor (with a deep link), vscode, gemini, goose, or the default mcpServers. The portal’s server pages show all of them.