What Is an MCP Server? Explained With a Real Example

The Plain-Language Definition

The Architecture: Host, Client, Server

MCP defines three roles. The names trip people up because two of them live in the same process, so here's the short version:

Tools, Resources, and Prompts

A server can advertise three kinds of capabilities, and it declares which ones it supports during the handshake:

Transports: stdio vs Streamable HTTP

The protocol messages are identical either way — what changes is how the bytes move:

What an MCP Tool Actually Looks Like

Tutorials love to show a get_weathertoy example. Here's a real one instead: wait_for_request, from Hooklistener's server. It blocks until a webhook request arrives on one of your debug endpoints, or until a timeout expires. When a client asks the server what it can do (via tools/list), this is roughly the definition it gets back:

{
  "name": "wait_for_request",
  "description": "Block until a webhook request arrives on a debug endpoint, or until timeout.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "endpoint_id": {
        "type": "string",
        "description": "ID of the debug endpoint to watch"
      },
      "timeout": {
        "type": "integer",
        "description": "Max seconds to wait (default 30, max 60). Set to 0 to only check for existing requests."
      }
    },
    "required": ["endpoint_id"]
  }
}

Notice that the schema does real work. The model reads the description and parameter docs to decide when and how to call the tool — there is no other documentation channel. The server, meanwhile, defends itself: the timeout is clamped to the 0–60 second range and defaults to 30 if the model sends something invalid. Good MCP tools are designed like public APIs, because that's exactly what they are.

When the model decides to use it, the client sends a JSON-RPC tools/call request. On a remote server this is an HTTP POST:

POST https://app.hooklistener.com/api/mcp
Authorization: Bearer <access-token>
Accept: application/json, text/event-stream
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "wait_for_request",
    "arguments": {
      "endpoint_id": "0b6e3c9a-...",
      "timeout": 60
    }
  }
}

The server verifies the endpoint exists, then subscribes to an internal pub/sub topic for that endpoint and blocks until a request is captured (the wait runs in a supervised task so a slow caller can't wedge the server). When a webhook lands, the response comes back as a JSON-RPC result whose content is the captured request:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"method\": \"POST\", \"path\": \"/\", \"headers\": { ... }, \"body\": { \"event\": \"payment.succeeded\", ... } }"
      }
    ],
    "isError": false
  }
}

If nothing arrives in time, the tool doesn't error — it returns a structured timeout the model can reason about: {"status": "timeout", "message": "No request received within 60 seconds."}. That distinction matters in practice: an assistant that gets a clean timeout can decide to retry, check configuration, or tell you the provider never fired — instead of choking on an exception.

Local vs Remote Servers — and How Auth Works

Local stdio servers mostly skip authentication: the process runs under your OS user, and any credentials it needs (a database password, an API key) arrive through environment variables in its config. Remote servers are a different story. They're multi-tenant services on the public internet, so they need to know who you are — and the MCP ecosystem has converged on OAuth 2.0 for that. Here's the actual flow Hooklistener's server implements, which is worth walking through because it's the same dance you'll see on most serious remote servers:

End to End: “Create a Webhook Endpoint and Wait for the Next Request”

Here's what actually happens, step by step, when you type that sentence into Claude Code with the Hooklistener server connected. This is the part most MCP explainers skip, and it's where the protocol stops being abstract.

Try a Real MCP Server in 2 Minutes

Reading about protocols only gets you so far. The fastest way to make MCP concrete is to connect to a live server and watch your assistant use it. With Claude Code:

claude mcp add --transport http hooklistener https://app.hooklistener.com/api/mcp

On first use, Claude Code walks the OAuth flow described above: your browser opens, you sign in, and the connection is live. No keys to copy. A free Hooklistener account is enough — the core endpoint and request tools work on the free plan. For clients that read a config file instead, the equivalent .mcp.json entry is:

{
  "mcpServers": {
    "hooklistener": {
      "type": "streamable-http",
      "url": "https://app.hooklistener.com/api/mcp"
    }
  }
}

Then ask your assistant something like “create a webhook endpoint and wait for the next request,” send a test webhook at the URL it gives you, and watch the loop close. The full tool list and per-editor setup live on the MCP page, and the AI coding assistants guide covers Cursor and other editors.

When an MCP Server Is the Wrong Tool

We ship an MCP server, so take this section as informed rather than dismissive: MCP is not the answer to everything, and bolting it on where it doesn't fit wastes effort.

Related Resources