> ## 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.

# How GetMCP Works

> What happens under the hood — from an AI client request to an API response.

GetMCP sits between your AI client and any REST API. It translates MCP protocol messages into HTTP requests — and HTTP responses back into MCP protocol messages — without you having to write a line of protocol code.

```
AI Client (Claude, Cursor, Windsurf)
        │
        │  MCP Protocol — JSON-RPC 2.0 over HTTP
        ▼
   WordPress + GetMCP
        │
        │  Configured HTTP request (GET / POST / PUT / etc.)
        ▼
   Your REST API (Stripe, GitHub, your own backend, etc.)
```

***

## The Request Lifecycle

Here is exactly what happens when an AI client calls one of your tools:

<Steps>
  <Step title="AI client sends a tools/call request">
    The AI client (Claude Desktop, Cursor, etc.) sends a JSON-RPC 2.0 POST request to your GetMCP server URL:

    ```http theme={null}
    POST https://yoursite.com/mcp/my-server
    Content-Type: application/json

    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "get_customer",
        "arguments": { "customer_id": "cus_123" }
      }
    }
    ```
  </Step>

  <Step title="GetMCP authenticates the request">
    If your server has inbound authentication enabled, GetMCP checks the `Authorization` header against the credential you configured. Requests without a valid credential are rejected with HTTP 403 before any API call is made.
  </Step>

  <Step title="GetMCP looks up the tool">
    GetMCP finds the `get_customer` tool in your server configuration and reads:

    * The endpoint URL (`https://api.yourcrm.com/customers/{customer_id}`)
    * The HTTP method (`GET`)
    * The input schema (to validate `customer_id` is present and a string)
    * The parameter mappings (`customer_id` → path variable)
    * The Custom Headers (your CRM API key)
  </Step>

  <Step title="GetMCP validates the arguments">
    The arguments (`{"customer_id": "cus_123"}`) are validated against the tool's JSON Schema. If a required parameter is missing or the wrong type, GetMCP returns an error immediately — no upstream request is made.
  </Step>

  <Step title="GetMCP builds and sends the HTTP request">
    GetMCP constructs the outbound HTTP request, injecting:

    * Path variables into the URL: `https://api.yourcrm.com/customers/cus_123`
    * Query params, if any, appended to the URL
    * Body params into the JSON body, if a POST/PUT/PATCH
    * Custom Headers (your production API key, never visible to the AI client)

    ```http theme={null}
    GET https://api.yourcrm.com/customers/cus_123
    Authorization: Bearer sk_live_your_crm_key
    ```
  </Step>

  <Step title="Your API responds">
    Your API processes the request and returns a response — typically JSON:

    ```json theme={null}
    {
      "id": "cus_123",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "plan": "pro",
      "created_at": "2024-01-15T10:30:00Z"
    }
    ```
  </Step>

  <Step title="GetMCP wraps the response in MCP format">
    GetMCP converts the API response into a valid MCP `tools/call` response — a JSON-RPC result containing the API response body as a text content block:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "{\"id\":\"cus_123\",\"name\":\"Jane Smith\",\"email\":\"jane@example.com\",...}"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="GetMCP logs the call">
    The call is recorded in the analytics database: timestamp, server, tool name, client type, client IP, HTTP status, response time in milliseconds. Credentials are never logged.
  </Step>

  <Step title="The AI client reads the result">
    Claude (or Cursor, or whichever client) receives the MCP response and uses the data to compose its reply to the user. The user sees a natural-language answer — not raw JSON.
  </Step>
</Steps>

***

## What GetMCP Is Responsible For

| Responsibility              | GetMCP                    | You                            |
| --------------------------- | ------------------------- | ------------------------------ |
| MCP protocol (JSON-RPC 2.0) | Handles automatically     | —                              |
| Streamable HTTP transport   | Handles automatically     | —                              |
| Session management          | Handles automatically     | —                              |
| Tool schema validation      | Handles automatically     | —                              |
| Inbound authentication      | Configure in Auth tab     | Share URL with clients         |
| Outbound API credentials    | Store in Custom Headers   | Provide the keys               |
| HTTP request construction   | Handles automatically     | Configure endpoints + mappings |
| Response → MCP format       | Handles automatically     | —                              |
| Call logging & analytics    | Handles automatically     | Review in dashboard            |
| Rate limiting               | Configure per server/tool | —                              |
| Retries on failure          | Configure retry count     | —                              |
| Response caching            | Configure cache TTL       | —                              |

***

## Tool Discovery (tools/list)

Before calling any tool, an AI client first calls `tools/list` to discover what's available. GetMCP returns the name, description, and input schema for every active tool on the server.

```
Claude connects to GetMCP server
  ↓
GET tools/list
  ↓  returns: get_customer, create_order, list_products …
Claude reads descriptions to understand what each tool does
  ↓
User: "Look up customer cus_123"
  ↓
Claude calls tools/call → get_customer
```

**This is why tool descriptions matter so much.** The AI's decision to call a tool — and which arguments to pass — is based entirely on the description you write. See [Best Practices](/docs/best-practices) for how to write descriptions that work.

***

## Resources and Prompts

Beyond tools, GetMCP also serves two other MCP protocol capabilities:

**Resources** — Read-only data the AI can pull on demand. When a client calls `resources/read`, GetMCP fetches the configured content (static text, external URL, or WordPress query result) and returns it as a content block. The AI can use this as context without triggering an action.

**Prompts** — Reusable instruction templates. When a client calls `prompts/get` with argument values, GetMCP renders the template (substituting `{{argument_name}}` placeholders) and returns the complete prompt text.

***

## What Runs on WordPress

GetMCP is a WordPress plugin. Everything runs inside your WordPress installation:

* **The MCP endpoint** is a WordPress REST route registered at `/mcp/{slug}`
* **The admin UI** lives in `wp-admin` under the GetMCP menu
* **All config** (servers, tools, credentials) is stored in the WordPress database — credentials encrypted with libsodium
* **All outbound HTTP requests** are made by WordPress using `wp_remote_request()`
* **Analytics** are stored in custom database tables created on plugin activation

No external service is involved in request handling. Requests go: AI client → your WordPress server → your upstream API. GetMCP never sees your traffic — it runs on your infrastructure.

***

## Performance Characteristics

| Factor           | Default    | Configurable             |
| ---------------- | ---------- | ------------------------ |
| Request timeout  | 30 seconds | Yes, per tool            |
| Retry on failure | 0 retries  | Yes, 0–5 per tool        |
| Response cache   | None       | Yes, TTL per tool        |
| Rate limit       | 60 req/min | Yes, per server and tool |

Caching is particularly useful for tools that call read-only endpoints with data that doesn't change frequently (product catalogs, reference data, documentation). Set a `Cache TTL` on those tools to reduce upstream API calls and improve response times.