Troubleshooting

Before digging into your client, confirm the server itself is reachable and advertising discovery correctly. An unauthenticated request should return 401 with a WWW-Authenticate header — that is success, not failure:

# Expect: 401 with a WWW-Authenticate header naming the metadata document
curl -i -X POST https://api.signvoy.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Expect: 200 with the protected-resource metadata
curl -s https://api.signvoy.com/.well-known/oauth-protected-resource/mcp

# Expect: 200 with the authorization-server metadata
curl -s https://api.signvoy.com/.well-known/oauth-authorization-server

The server does not appear in my client at all

Almost always malformed JSON in the config file — a trailing comma after the last entry is the most common cause. Clients tend to fail silently rather than reporting a parse error. Validate the file:

# macOS / Linux — prints an error if the JSON is invalid
python3 -m json.tool ~/.cursor/mcp.json

python3 -m json.tool \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

Also confirm you restarted the client. Claude Desktop reads its config only at startup, so a reload is not enough — quit fully and reopen.

The server appears but lists no tools

Tool discovery happens after authentication. A connected server with zero tools means the OAuth flow has not completed — look for a login or authenticate control next to the server in your client's MCP settings and run it.

It lists fewer tools than documented

Discovery was interrupted partway through. Toggle the server off and on to force a fresh tools/list. Compare against the tool reference to see what is missing.

It keeps asking me to authenticate

A consent loop means the token is not surviving between calls. Three things to check, in order:

• Duplicate entries in your config pointing at the same URL under different names — each registers separately and they can fight over the grant.
• The client cannot write to its credential store, so the token is discarded after each session.
• The grant is being revoked externally. Confirm it still exists under Workspace Settings → AI Agents, or with GET /v1/mcp-grants.

“Ambiguous workspace” on a tool call

Your account belongs to more than one workspace and the call did not say which to use. This is deliberate: guessing would let an agent draft or send a contract from the wrong workspace, which is not something you can undo after the emails go out. The error lists the workspaces with their UUIDs, so tell your assistant which one you meant and it can retry straight away — pass workspace_id on every subsequent call in that conversation.

The agent is acting on the wrong workspace

A workspace is only ever chosen by the tool call itself, so this means the assistant passed a workspace_id you did not intend. Ask it to run signvoy_list_workspaces and confirm which UUID it is using. Drafts created in the wrong workspace cannot be moved; void them and recreate rather than trying to transfer.

The same grants are available over the API if you would rather script it:

# List your active grants
curl -s https://api.signvoy.com/v1/mcp-grants \
  -H "Authorization: Bearer sk_live_..."

# Revoke one — the client will re-run consent on its next call
curl -X DELETE https://api.signvoy.com/v1/mcp-grants/<grant-id> \
  -H "Authorization: Bearer sk_live_..."

These are transport-level errors — the request never reached a tool. Failures inside a tool are different: they come back as a normal result with isError: true and a prose message naming the constraint and the fix, which is what the model reads.

Tools enforce the document state machine. These are the constraints people hit most:

120 requests per 60 seconds, bucketed per OAuth token — so each client has its own budget and one hitting the ceiling does not throttle the others. Exceeding it returns -32003.

Pointing a client at a local API works, but two things trip people up. The API listens on the port set by PORT, which defaults to 3001 — check what your instance actually bound before assuming a port:

{
  "mcpServers": {
    "signvoy-local": {
      "url": "http://localhost:3001/mcp",
      "transport": "streamable-http"
    }
  }
}

Second, OAuth discovery points at the configured MCP_RESOURCE_URL and CLERK_OAUTH_ISSUER. If those still reference production while the server runs locally, your client will register against the wrong authorization server and consent will fail. Keep both consistent with the environment you are running.