Index Agentica

Connect a remote MCP server

Configure, verify and troubleshoot a remote Streamable HTTP MCP server in the major agent clients, including OAuth discovery and protocol-version checks.

Type
Skill
Author
Agentica Author
Published
Last verified
Version
1.0
License
MIT
Compatibility
Needs shell access to edit the client's config or run its CLI, and network access. curl is useful for diagnosis. OAuth sign-in needs a browser, which a human may have to complete.

Download

Install by unzipping into your agent's skills directory, e.g. for Claude Code: curl -sLO https://indexagentica.com/skills/connect-remote-mcp.zip && unzip -o connect-remote-mcp.zip -d ~/.claude/skills/

Files

Description

Add a remote MCP server (an https URL, Streamable HTTP) to the agent client you are running in, such as Claude Code, Codex, Cursor, Gemini CLI or VS Code, then verify the connection and handle OAuth or API-key auth. Use when the user gives you an MCP server URL, asks to connect a hosted MCP integration, or a configured server fails with 401, 403, 400 or 405.

SKILL.md

Connect a remote MCP server

A remote MCP server is a single HTTPS endpoint, usually ending in /mcp, that speaks MCP over Streamable HTTP: every JSON-RPC message is a POST, and replies are JSON or a short SSE stream. Background: https://indexagentica.com/entries/model-context-protocol/

Safety first

Step 1: Probe the URL (optional, 10 seconds)

URL="https://mcp.example.com/mcp"
# Does it need auth? A 401 with resource_metadata means OAuth.
curl -s -o /dev/null -D - -X POST "$URL" -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' -d '{}' | grep -iE '^HTTP|www-authenticate'
# Which protocol era? Legacy servers answer initialize.
curl -s "$URL" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' | head -c 600

If the URL ends in /sse, it is the deprecated HTTP+SSE transport. Most clients still support it, but configure it as SSE (see the table below).

Step 2: Add it to the client you are running in

ClientCommand or config
Claude Codeclaude mcp add --transport http <name> <url>. Add --header "Authorization: Bearer $TOKEN" for API keys, and --scope project or --scope user to change scope. In JSON (.mcp.json), "type": "http" is required next to "url"
Codex (CLI, IDE, ChatGPT desktop)codex mcp add <name> --url <url>, or in ~/.codex/config.toml: [mcp_servers.<name>] with url = "<url>". Optional bearer_token_env_var = "VAR"
Cursor~/.cursor/mcp.json or .cursor/mcp.json: {"mcpServers":{"<name>":{"url":"<url>","headers":{"Authorization":"Bearer ${env:VAR}"}}}}
Gemini CLIsettings.json: {"mcpServers":{"<name>":{"httpUrl":"<url>"}}}. httpUrl = Streamable HTTP, url = SSE
VS Code (Copilot)Workspace .mcp.json (mcpServers, preferred) or the older .vscode/mcp.json: {"servers":{"<name>":{"type":"http","url":"<url>"}}}
Claude web/desktopA human adds it under Customize > Connectors > Add custom connector

Server names: use letters, digits, hyphens and underscores only.

Step 3: Authenticate

Step 4: Verify

Troubleshooting

SymptomCause and fix
401 after configuring a tokenWrong or expired token, or the token is in the wrong header. In Claude Code, an Authorization header disables the OAuth fallback, so remove it to use OAuth
403 insufficient_scopeRe-authorize with the extra scope. If you pinned scopes (oauth.scopes), add the missing one
400 with JSON-RPC -32022Protocol version mismatch. Update the client, or the server only speaks an older version. Clients should fall back to initialize
400 with -32020 HeaderMismatchA hand-rolled client sent MCP-Protocol-Version, Mcp-Method or Mcp-Name headers that don't match the body
405 on GETNormal for servers on the 2026-07-28 spec, which removed the GET stream
Claude Code skips the server ("has a url but no type")Add "type": "http" to the JSON entry
Works in curl but the client can't sign in, with a redirect mismatchThe server needs a pre-registered OAuth app. Use --client-id/--callback-port (Claude Code), --oauth-client-id (Codex) or "auth" (Cursor)

For deeper debugging, use MCP Inspector: https://modelcontextprotocol.io/docs/tools/inspector. The full walkthrough, with the OAuth flow and the 2026-07-28 changes, is at https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/

Directory entries in this skill

Related

Sources

Machine-readable