Other MCP clients
Connect any MCP client to SpecsGraph with OAuth sign-in or a bearer token, bridge stdio-only clients with mcp-remote, and fix common connection errors.
What your client needs
SpecsGraph works with any MCP client that can reach a remote server over streamable HTTP: the client sends MCP messages as HTTP POST requests to one URL. Then it needs one of these to authenticate:
- MCP sign-in (OAuth). Clients that support MCP sign-in find it on their own: the first request gets
401with a pointer to SpecsGraph, the client opens your browser, and you allow the agent on a consent page. There is no token to copy or store. The details are in Sign in with OAuth. - Custom request headers. The client sends
Authorization: Bearer <token>on every request, with a personal access token that starts withsgp_.
Claude Code, Codex, Cursor and GitHub Copilot have their own guides under Connect an agent.
Generic configuration
Many clients describe servers in a JSON file with an mcpServers object. With sign-in, the entry needs only the URL; the client asks you to sign in when it first connects:
{
"mcpServers": {
"specsgraph": {
"type": "http",
"url": "https://mcp.specsgraph.io/mcp"
}
}
}For a client without sign-in, add "headers": { "Authorization": "Bearer sgp_..." }, reading the token from an environment variable when the client supports it. Clients differ in the details: some name the top-level key servers, some infer the transport and reject a type field. 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. mcp-remote can run the OAuth sign-in itself; to send a token instead, pass the header:
{
"mcpServers": {
"specsgraph": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.specsgraph.io/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, which avoids clients that split 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 with a token. A working setup answers 200 with the server's name, specsgraph, and its capabilities. Without a token, the answer is 401 with a WWW-Authenticate header naming the resource metadata, which is what sign-in starts from.
curl -sS -i -X POST https://mcp.specsgraph.io/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"}}}'A 401 here means the token is the problem, not your client; the body says which case (missing header, no Bearer, unexpanded variable, malformed, unknown, expired, revoked). The server only accepts POST. The web app's Test connection button in the token created dialog runs this initialize plus tools/list from your browser and reports that the server lists 52 tools, starting with project_list, or the matching row below.
Troubleshooting
Two more answers you may see: 406 Not Acceptable means the Accept header lacks application/json or text/event-stream; 429 with Retry-After means too many requests, for example more than 60 writes a minute on one token. For problems outside the connection itself, see Troubleshooting.
Still stuck? Email support@specsgraph.io with the time of the request and the status you saw, or see Support.
Next steps
- MCP tool reference: the tools your client should list once connected.
- Sign-in and access tokens: consent, scopes and revocation.
- Connect an agent: how requests flow from client to SpecsGraph.