Common issues#

The server isn't appearing in my client#

Check that your client supports HTTP transport. Not all MCP clients support Streamable HTTP — some only support stdio (local process) connections. The Trustgrid MCP server is HTTP-only. Verify your client's MCP documentation.

Check the URL format. The URL must include the path prefix:

https://mcp.trustgrid.io/mcp          ✓ correct
https://mcp.trustgrid.io              ✗ missing /mcp
https://mcp.trustgrid.io/mcp/         ✓ trailing slash is fine

Check your domain. If your organization has a tenant-specific endpoint (e.g., mcp.acme.trustgrid.io), use that rather than the default mcp.trustgrid.io. If you use the portal at <your-company-name>.trustgrid.io, your MCP endpoint is mcp.<your-company-name>.trustgrid.io.

I'm getting 401 Unauthorized#

Missing or malformed header. Confirm the Authorization header is present and uses the correct format:

# API token
Authorization: trustgrid-token YOUR_CLIENT_ID:YOUR_CLIENT_SECRET

A common mistake is using Bearer with an API token: Bearer clientId:secret won't work. Use trustgrid-token clientId:secret.

OAuth loop. If the server returns a WWW-Authenticate challenge and your client doesn't handle OAuth, it may retry indefinitely. Configure a static token in the headers instead.

I'm getting 403 Forbidden#

Your credentials are valid but lack permission for the requested operation. Check:

• The API key was generated for the correct user account
• The user account has appropriate permissions in the Trustgrid portal
• You're using the correct endpoint path — /mcp/tools requires node service scopes that /mcp/read does not request

Tools work but return errors for specific nodes#

Node is offline. Most diagnostic tools require the node to be reachable. If the node is disconnected from the control plane, test_* tools will time out or return an error.

Rate limit errors (429)#

You're hitting the per-token request limit for the active group. Limits are:

• codemode: 10 requests / 60 seconds
• read: 30 requests / 60 seconds
• tools: 10 requests / 60 seconds

The response includes Retry-After header with the wait time in seconds. If you're hitting limits consistently, consider using the read group instead of codemode for read-heavy workflows, or split high-frequency queries across multiple credentials.

OAuth won't complete / browser auth fails#

Check the MCP URL. OAuth flows redirect through portal.trustgrid.io or your tenant portal URL. If your network blocks the portal, the OAuth flow will fail. Use a static API token instead.

Check for cookie blockers. Some browser extensions block third-party cookies and can interfere with OAuth callbacks. Try in a private window.

The code tool says "not allowed" or isn't available#

The code tool is only in the codemode group (/mcp/codemode or /mcp). If you're connected to /mcp/read or /mcp/tools, the code sandbox isn't available. Change your client config to point at /mcp or /mcp/codemode.

Submit feedback#

Found a bug, missing tool, or unexpected behavior? Open an issue at:

github.com/trustgrid/mcp-features

Helpful things to include in your report:

• Client name and version — e.g., "Claude Code 1.2.3", "Cursor 0.45"
• Tool group / endpoint URL — /mcp/codemode, /mcp/read, etc.
• The tool that failed — the exact tool name (e.g., test_tcp_connectivity, code)
• What you asked for — the prompt or tool call that triggered the issue
• What you got back — the error message or unexpected response, including HTTP status codes if visible
• What you expected — a brief description of the intended behavior
• Auth method — OAuth or API token (don't include the actual credential)

The more context you provide, the faster we can reproduce and fix it.