Skip to content

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 401 with 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 with sgp_.
ValueWhat to use
URLhttps://mcp.specsgraph.io/mcp
Protected resource metadatahttps://mcp.specsgraph.io/.well-known/oauth-protected-resource/mcp
Authorization serverhttps://app.specsgraph.io: dynamic client registration, PKCE with S256, public clients, refresh tokens and revocation
Scopespecsgraph
Token header, without sign-inAuthorization: Bearer sgp_...

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:

Client MCP configurationJSON
{
  "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:

Client MCP configuration with mcp-remote and a tokenJSON
{
  "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.

Shell
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

SymptomLikely causeWhat to do
401 Unauthorized with a tokenThe header is missing, lacks the word Bearer, or the token is expired or revoked. A header that still contains ${SPECSGRAPH_TOKEN} means the client did not expand the variable.Test with curl. Check that SPECSGRAPH_TOKEN is set in the environment that starts your client. If the token is gone, create a new one.
The client asks you to sign in again, or reports 401 UnauthorizedThe agent's sign-in was revoked in Signed-in agents, it reached the expiry you chose on the consent page, or your membership of the organisation ended.Connect again from the client and allow the agent on the consent page. Nothing the agent staged before is lost.
The consent page says "This sign-in request expired" or "was already answered"The sign-in link is single use and short lived. It was opened late, twice, or in another browser.Go back to the client and connect again, then finish the consent page in one go.
The consent page says "You are not in an organisation yet"An agent always acts in one organisation, and your account has none.Create an organisation or accept an invitation in the web app, then connect again.
You chose Deny, or closed the consent pageThe client did not get access.Connect again and choose Allow.
Connected, but some tools are refusedThe agent was allowed Read only, the project is not among the projects you chose, or your role is below Editor.Revoke the agent in Signed-in agents and connect again with Read and write and the right projects, or ask an Admin for the Editor role.
403 Forbidden, or a tool error saying access is deniedThe access is valid but not allowed to do this: Read only access called a write tool, the project is not included, or your role does not allow the action. Acts that belong to people, such as submitting a task as Ready, have no tool at all.Check the access and projects in Settings, then Access tokens, and your role in Members and roles.
404 Not FoundThe URL is wrong, often a missing path.Copy the MCP URL exactly, path included: https://mcp.specsgraph.io/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 on your network blocks the SpecsGraph host, or buffers streamed responses.Allow outbound HTTPS to mcp.specsgraph.io and app.specsgraph.io, and ask whoever runs your proxy to stop buffering or cutting off long requests to them.

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