Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getmcp.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Connection Issues

Symptoms: Client shows “connection refused”, “server not found”, or times out on connect.Check these in order:
  1. Your WordPress site uses HTTPS — most MCP clients require it
  2. The server status is Active in GetMCP → your server → Settings
  3. The URL is copied exactly (slug and server ID both correct — they’re case-sensitive)
  4. WordPress rewrite rules are flushed: go to Settings → Permalinks and click Save Changes without changing anything
  5. No firewall or security plugin (Wordfence, Cloudflare WAF) is blocking requests to /mcp/*
To confirm the endpoint is reachable, run:
curl -X POST https://yoursite.com/mcp/your-slug \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}'
A {"jsonrpc":"2.0","id":1,"result":{}} response confirms the server is up.
Cause: Your server has inbound authentication enabled and the client isn’t sending the right credential.Fix:
  • Confirm the Authorization header is present in your client config
  • Verify the token matches exactly what’s set in Server Settings → Authentication
  • If using mcp-remote (Claude Desktop), auth must be passed as --header args — not as a headers key. The headers key is not supported by mcp-remote:
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://yoursite.com/mcp/slug/id",
        "--header",
        "Authorization:Bearer YOUR_KEY"
      ]
    }
  }
}
The server is Paused. Go to GetMCP → your server → Settings and set the status to Active.
  1. Check each tool’s status is Active (not Paused)
  2. Ask the client to refresh: “What tools do you have available?”
  3. In Claude Desktop, fully quit and relaunch — it doesn’t hot-reload MCP config
  4. Confirm the server URL in the client config matches your actual server URL
  5. Check GetMCP → Analytics — a tools/list call should appear after the client connects

​
Tool Call Failures

Symptoms: Tool call returns isError: true with an HTTP error code from your API.Debug steps:
  1. Open the tool and click Test — run it with the same arguments to see the raw request and response
  2. Check that the Endpoint URL is correct — try calling it directly with curl
  3. Verify credentials in Custom Headers are still valid (tokens expire)
  4. Check that required parameters are mapped to the right location (Path / Query / Body)
Call logs in Analytics → Call Logs show the exact HTTP status returned by your API for every call.
The AI didn’t supply a required parameter. This usually means the tool description or parameter description wasn’t clear enough for the AI to know what value to provide.Fix:
  • Make parameter descriptions explicit: “The customer’s unique ID, e.g. cus_abc123”
  • If the parameter is always optional in practice, uncheck Required
  • See Best Practices for writing descriptions that the AI follows reliably
The AI is sending a value the API rejects — wrong format, wrong type, out of range.Fix:
  • Add an enum to constrain fixed choices
  • Add a description that shows the expected format: “ISO 8601 date string, e.g. 2024-01-15”
  • Add minimum / maximum for numeric ranges
  • Add a pattern for regex-validated strings
If your URL is https://api.example.com/users/{{user_id}} but the request goes to the literal string /users/{{user_id}}, the parameter mapping is wrong.Fix: Open the tool, find the user_id parameter in the Input Schema, and set its Mapping to Path. The placeholder in the URL must match the parameter name exactly including case.
Common causes:
  • Parameter mapping is set to Query but your API expects a JSON Body
  • HTTP Method is GET — GET requests don’t have a body; switch to POST or move params to Query
  • JSON body is malformed — use the Test panel to inspect the outgoing request
Very large API responses slow down AI clients and may be truncated.Options:
  • Add pagination parameters (limit, page) and instruct the AI in the description to request smaller pages
  • Use Response Mapping to extract only the field you need (e.g. data.results) instead of returning the full body
  • Enable Cache TTL on read-only tools so the large payload is fetched once and cached

​
Authentication Issues

Check the header name exactly. Header names are case-sensitive on some APIs. If your curl uses X-API-Key and the tool header uses x-api-key, they may behave differently.Also verify there are no leading or trailing spaces in the credential value — these are invisible but cause auth failures.Use the Test panel → inspect the outgoing request to confirm the header is being sent with the correct value.
Static tokens stored in Custom Headers don’t refresh automatically.Options:
  • Use an API key instead of a short-lived bearer token where the upstream API allows it
  • For user-supplied credentials, have users update their MCP client config with the new token
  • For fixed credentials, update the Custom Header in the tool’s settings whenever the token rotates
If you’re using Layer 2 auth (users pass their own key in the client config headers block), confirm:
  1. The header name in the client config matches what your API expects (e.g. X-API-Key)
  2. GetMCP’s server auth is set to pass-through or the same header — not overriding it
  3. The tool’s Custom Headers don’t overwrite the user’s header with an empty or default value
See Authentication for the full two-layer auth diagram.

​
Performance Issues

Check in order:
  1. Upstream API latency — test the endpoint directly with curl and time it. If the API is slow, that’s the ceiling.
  2. WordPress server resources — GetMCP uses wp_remote_request() which runs synchronously. A low-resource shared host adds overhead.
  3. Timeout setting — if calls are hitting the 30s default timeout, reduce it in Advanced Settings to fail fast instead of hanging
  4. Enable caching — for read-only tools that return the same data frequently, set a Cache TTL to avoid repeated upstream calls
GetMCP’s own rate limiter is separate from your upstream API’s limits. If your API returns 429s:
  • Reduce the per-server rate limit in GetMCP so calls stay under your API’s quota
  • Enable Cache TTL on high-traffic read tools to reduce call volume
  • Check Analytics → Call Logs to see which tool is generating the most calls

​
Analytics & Logs

Calls are logged after a tool successfully completes. If logs are empty:
  • Confirm the database tables were created — deactivate and reactivate the plugin to re-run the installer
  • Check that the WordPress user running the site has CREATE TABLE privileges
  • Verify calls are actually reaching the server (check your server access logs for POST requests to /mcp/*)
The Test panel uses Test Credentials (server-level). Production calls from AI clients use Custom Headers (production credentials). An error visible in analytics but not in testing usually means the production credential is wrong or expired.

​
Still Stuck?

If none of the above resolves your issue:
  1. Run the ping test from the curl command above to confirm basic connectivity
  2. Check Analytics → Call Logs for the exact error on the failing call
  3. Use MCP Inspector to run the call interactively and inspect the raw request/response — see MCP Inspector