Home Glossary
HomeGlossaryMCP Capability
MCP Glossary

MCP Capability

TL;DR

An MCP capability is a feature flag exchanged during the initialization handshake, declaring what an MCP server supports (tools, resources, prompts, sampling, logging, etc.) and what the client supports. Capability negotiation makes MCP extensible — new features can be added without breaking existing implementations.

In depth

MCP capabilities are declared during the initial handshake. When a client calls `initialize`, it sends its own capabilities (things it supports, like `sampling` or `roots/listChanged`). The server responds with its capabilities (`tools`, `resources`, `prompts`, `logging`, `completions`, etc.).

This bidirectional declaration lets clients and servers negotiate what features to use. A client that doesn't support `sampling` should never receive sampling requests; a server that doesn't support `prompts` won't advertise a prompts list. Capability checking is the official way to detect optional features.

Capabilities can be nested — e.g. `tools: { listChanged: true }` means the server supports the `tools/list_changed` notification. This lets future additions be introduced without breaking existing servers (which simply don't advertise the new capability).

Capabilities are the forward-compatibility story of MCP. New versions of the spec add new capabilities; old clients simply don't negotiate them.

Code example

// Initialize handshake
// Client → Server
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": { "name": "claude-code", "version": "0.5.0" }
  },
  "id": 1
}

// Server → Client
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": {},
      "logging": {}
    },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  },
  "id": 1
}

Examples

  • 1
    `tools: {}` — server supports tools
  • 2
    `resources: { subscribe: true }` — server supports resource subscriptions
  • 3
    `prompts: { listChanged: true }` — server notifies on prompt list changes
  • 4
    `sampling: {}` — client allows server to request LLM completions
  • 5
    `roots: { listChanged: true }` — client tracks filesystem roots

What it's NOT

  • ✗Capabilities are NOT user permissions — they're protocol feature flags.
  • ✗Missing capabilities do NOT cause errors — they just mean the feature isn't available.
  • ✗Capabilities are NOT runtime-negotiated every request — they're fixed at session start.
  • ✗Capabilities are NOT the same as tool permissions — permissions are declared per-tool.

Related terms

Model Context Protocol (MCP)MCP InitializeMCP SessionMCP ServerMCP Client

See also

  • MCP Lifecycle

Frequently asked questions

How do I add a new capability to my server?

Declare it in the `initialize` response. Clients will check for it before using the feature. Undeclared capabilities are assumed off.

Do I need to declare all capabilities?

No — only the ones you support. An empty capability object `{}` means 'present but no sub-features'.

Can capabilities change mid-session?

No — they're fixed at initialize. List-changed notifications communicate content changes, not capability changes.

Build with MCP

Browse 300+ MCP servers, explore recipes, or continue learning the MCP vocabulary.

Browse MarketplaceAll terms