Skip to content

Other MCP clients

Connect any MCP client to SpecsGraph with the server URL and a bearer token, or bridge stdio-only clients with mcp-remote. Includes a troubleshooting table.

What your client needs

SpecsGraph works with any MCP client that can reach a remote server. The client needs two things:

  • Streamable HTTP transport. The client sends MCP messages as HTTP requests to one URL.
  • Custom request headers. The client sends Authorization: Bearer <token> on every request, with a personal access token that starts with sgp_.
ValueWhat to use
URLYour server's MCP URL: SPECSGRAPH_PUBLIC_URL plus /mcp, such as https://specsgraph.example.com/mcp, or SPECSGRAPH_MCP_PUBLIC_URL if set
Header nameAuthorization
Header valueBearer sgp_...

If your client supports both, you are done after the next section. If it can only start local processes, use the bridge described after it.

Generic configuration

Many clients describe servers in a JSON file with an mcpServers object. A remote SpecsGraph entry usually looks like this:

Client MCP configurationJSON
{
  "mcpServers": {
    "specsgraph": {
      "type": "http",
      "url": "https://specsgraph.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sgp_paste-your-token-here"
      }
    }
  }
}

Clients differ in the details. Some name the top-level key servers, some use a different key for the URL, some infer the transport and reject a type field. Most support a way to read the token from an environment variable, so prefer that over pasting the token when the file could be shared. The client's own documentation is the authority on its format.

Clients that only support stdio

Some clients can only launch a local command and talk to it over standard input and output. Bridge them with mcp-remote (opens in a new tab), a small open-source package that runs locally, speaks stdio to your client and forwards everything to the remote server. It needs Node.js, and npx downloads it on first use.

Client MCP configuration with mcp-remoteJSON
{
  "mcpServers": {
    "specsgraph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://specsgraph.example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer sgp_paste-your-token-here"
      }
    }
  }
}

mcp-remote replaces ${AUTH_HEADER} with the variable from the env block. Keeping the space inside the variable, rather than writing Authorization: Bearer ... directly in args, avoids clients that split or mangle arguments containing spaces. This file holds the token, so keep it out of version control. Check the mcp-remote README for its current flags.

Test the endpoint with curl

To rule out the client, send an MCP initialize request yourself. A working setup answers with the server's name and capabilities, either as JSON or as a short event stream.

Shell
curl -sS -X POST https://specsgraph.example.com/mcp \
  -H "Authorization: Bearer $SPECSGRAPH_TOKEN" \
  -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":"curl","version":"1.0"}}}'

Add -i to see the HTTP status. A 401 here means the token is the problem, not your client. If the server supports a different protocol revision, it answers with the one it supports, and that is fine for this test.

Troubleshooting

SymptomLikely causeWhat to do
401 UnauthorizedThe header is missing, lacks the word Bearer before the token, or the token is expired or revoked. A header that contains a literal ${...} means the client did not expand the variable.Test with curl. Check that the variable is set where the client starts. If the token is gone, create a new one.
403 Forbidden, or a tool error saying access is deniedThe token is valid but not allowed to do this: a Read only token called a write tool, the project is not on the token, or your role does not allow the action.Check the token's access and projects in Account settings, then Access tokens, and your role in Members and roles.
404 Not FoundThe URL is wrong, often a missing /mcp path.Copy your server's MCP URL exactly, path included, as in https://specsgraph.example.com/mcp.
Connected, but no tools listedThe client cached an earlier failed connection, the tools are turned off in the client's tool picker, or the client caps the total number of tools across servers.Restart the client or reconnect the server. Enable the SpecsGraph tools, and turn off tools from servers you do not need.
Timeouts or dropped connectionsA firewall or proxy blocks your server's host, a proxy buffers streamed responses, or your reverse proxy closes long requests.Allow outbound HTTPS to your server's host, such as specsgraph.example.com. Turn off response buffering for the MCP path and raise read timeouts; see Configuration.

For problems outside the connection itself, such as publishing or sign-in, see Troubleshooting.

Next steps