How MCP works: The protocol behind AI tool integration

TL;DR

• MCP lets AI models discover and call external tools at runtime using JSON-RPC messages, replacing hardcoded API integrations.

• Three roles define every session: the Host (Claude Desktop, Cursor), the Client (the protocol module inside the host), and the Server (the process exposing tools).

• Composio's MCP Gateway consolidates 1,000+ pre-built tools into one managed endpoint with built-in auth and access control.

• Two transports handle connectivity: stdio for local servers the host spawns as a child process, and Streamable HTTP for remote servers that need to serve multiple clients. Use a managed gateway when you don't want to run and maintain those server processes yourself.

Your AI assistants live in a sandbox, cut off from the tools where you actually work. Every context switch is a manual step, and those steps compound into hours every week. The Model Context Protocol (MCP) is the protocol Anthropic released in November 2024 that fixes this at the infrastructure level, giving AI models a standardized way to discover and invoke real tools at runtime.

This guide walks through exactly how that works: the client-server model, the JSON-RPC message format, the startup handshake, and how Composio's managed gateway removes the operational overhead of running those servers yourself.

How MCP solves the fragmented tool problem

Ending manual app hand-offs

If you use Claude Desktop or Cursor daily, you know the friction. You ask the model to summarize Slack threads, then manually paste them in. You want it to create a GitHub issue from a support ticket, so you copy the text, switch windows, fill in the form, and switch back. The model has the reasoning capability to do those tasks end-to-end, but no way to actually reach the tools.

MCP vs. standard API design

Traditional REST integration follows a developer-driven pattern: you write code that calls a specific endpoint, handle the response format, and repeat that process for every service you connect. When the API changes, you update the code. The model plays no role in deciding which endpoint to call.

MCP inverts that control. The server declares its own capabilities at runtime through a tools/list response, and the model decides which tool to call based on the user's intent. No hardcoded conditionals. No custom glue code per service.

MCP roles: Client, server, and host

Defining the three core roles

Define the roles first, and the mental model holds together. The Host is the AI application managing your session, like Claude Desktop or Cursor. The Client is the embedded protocol module inside the host that speaks MCP. The Server is a focused process exposing tools, resources, and prompts. Think of these as the Brain (the AI model reasoning), the Nervous System (the protocol carrying messages), and the Hands (the servers executing real actions).

• Host: The application running on your machine, like Claude Desktop or Cursor. The host owns the user session and manages which servers the model can reach.

• Client: The embedded module inside the host that sends requests, receives responses, and translates between what the model wants and what the protocol requires.

• Server: A focused process exposing tools, resources, and prompts. A GitHub server exposes issue creation, PR review, and repository search. A Gmail server exposes search, send, and label management.

Linking your AI to external data

The protocol enforces structure at every step. You never send raw user prompts to the server. The client translates them into validated JSON-RPC requests first, and the server returns structured content the LLM can parse reliably. Composio's MCP Gateway acts as a single endpoint routing tool calls to 1,000+ pre-built, maintained integrations, replacing the need for separate server processes per app. The sessions via MCP documentation explains how session-based routing works in practice.

Using Claude Desktop to host MCP

Claude Desktop reads server definitions from a JSON configuration file. On macOS, that file lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it's at %APPDATA%\Claude\claude_desktop_config.json. You can open it directly or reach it through Settings, then Developer, then Edit Config.

The command field tells the host how to start the server process, and args passes the path to your server script:

{
  "mcpServers": {
    "my-tool-server": {
      "command": "node",
      "args": ["/path/to/my-server/index.js"]
    }
  }
}

The host reads this file at startup, spawns the server processes, and runs the initialization handshake before the model becomes available.

Standardizing your AI data flow

JSON-RPC message structure

MCP uses JSON-RPC 2.0 as its message format. JSON-RPC is a lightweight, language-agnostic remote procedure call protocol, which means any server in any runtime can implement it without specialized libraries. A JSON-RPC 2.0 request typically includes a jsonrpc field (always "2.0"), a method name, and optionally an id for correlating responses and params carrying the inputs. For Streamable HTTP transport, requests also include Mcp-Method and Mcp-Name HTTP headers that enable header-based routing at the infrastructure layer. Every MCP result includes a resultType field that marks whether the result is a normal completion or an input_required continuation requiring additional round trips. Responses to tools/list must include resultTypettlMs and cacheScope fields that allow clients and gateways to cache the tool catalog between calls. The params and id fields may be omitted depending on the request type:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/home/user/notes.txt"
    },
    "_meta": {
      "protocolVersion": "2026-07-28"
    }
  }
}

Responses follow a matching structure, using the same id so the client can correlate the result to the original call.

Mapping commands to server responses

When you type "summarize my last five emails" in Claude Desktop, the model consults the tool schemas returned by tools/list or server/discover, identifies the Gmail search tool as the right match, and generates a structured tool-call request with the correct parameters. The client sends that request to the server. The server executes the Gmail API call, formats the response as structured content, and returns it. The model reads that result and generates the summary.

Connecting your tools via MCP

Composio's SDK reduces server configuration to a few lines:

import { Composio } from '@composio/core';

const composio = new Composio({
  apiKey: 'your-api-key'
});

const { mcp } = await composio.create('your-user-id');

That single URL gives your host access to all tools tied to your user's authenticated connections, without spawning a separate process for each one. The single toolkit MCP documentation shows how to scope that endpoint to a specific app when you need a narrower surface area.

The free tier gives you 100,000 tool calls per month with no credit card required, which is enough to build and validate a complete agent workflow before committing to a paid plan.

How the stateless protocol model works

The 2026-07-28 MCP specification removed the initialize/notifications/initialized handshake entirely (SEP-2575). The protocol is now stateless: every request carries its own protocol version and capability declarations inside a _meta field, and the server processes each request independently without a prior session setup.

Tool discovery no longer requires a full session to be established. Servers expose an optional server/discover endpoint that returns server metadata and available tools in a single call, making it possible to inspect a server's surface area before sending any tool calls. The tools/list method still works for in-session catalog browsing and remains the standard discovery path when server/discover is not implemented.

Cached results take advantage of new response fields that allow list responses like tools/list to be cached at the client or gateway layer, reducing redundant round trips when the tool catalog hasn't changed.

Executing tasks through standardized tool calls

Every tool exposed by an MCP server is declared using JSON Schema, which defines the tool's name, description, and the exact parameters it accepts. For example, a calculate_sum tool specifies two required number parameters (a and b) with the description "Add two numbers together." The description field matters beyond documentation: the model reads it to decide whether this tool matches the user's intent.

When the client sends a tools/call request, it validates the model's arguments against the tool's inputSchema. A missing required field or a type mismatch surfaces at the client layer before any server-side execution happens, catching malformed requests early.

Servers aim to return structured content objects that the LLM can parse reliably, though the specification also allows unstructured fallback content to handle variations gracefully. The goal is to avoid returning raw, unfiltered API payloads that would bloat the model's context window. A Gmail search returning 50 raw message objects as unfiltered JSON creates a context management problem. A properly structured MCP response returns a clean list of message summaries with the fields the model actually needs.

A native Salesforce MCP server exposes just over 60 tools, while Composio's Salesforce toolkit exposes over 100 tools, each returning pre-validated, LLM-optimized schemas.

Those schemas are continuously refined through Composio's self-learning layer, which observes patterns across 300M+ tool calls per month and uses that signal to improve schema descriptions and parameter guidance. The result: agents running on Composio's toolkits show 30% better accuracy on tasks that previously required twice as many tokens to complete, with smaller context windows and lower API costs.

How version negotiation prevents failures

Because the 2026-07-28 spec is stateless, version negotiation happens on every request rather than once at session start. Each request carries its protocolVersion in _meta, and the server evaluates it independently. If the version is unsupported, the server returns a standard JSON-RPC error for that request — no session teardown required, and no dependency on a prior handshake completing successfully. The MCP specification, published July 28, 2026, introduced this stateless protocol core alongside header-based routing, cacheable list results, and authorization hardening. Keeping server dependencies current eliminates this class of failure, or you can use Composio's managed gateway, which handles version compatibility as part of its maintenance layer.

Message structures to master

Browse your accessible tool library

The tools/list method retrieves every tool the server makes available in the current session:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

The server responds with an array of tool objects, each containing its name, description, and input schema. This is the catalog the model references when deciding how to respond to a user prompt.

Triggering actions with AI commands

The tools/call method is where actual execution happens:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "send_email",
    "arguments": {
      "to": "team@example.com",
      "subject": "Weekly summary",
      "body": "Here are this week's highlights..."
    }
  }
}

Composio's Tool Router adds a routing layer on top of this standard call. The agent doesn't need to know whether you have Gmail or Outlook connected. Tool Router inspects your authenticated connections and routes the send_email call to the correct provider automatically, eliminating conditional logic in your agent code and letting users swap email providers without any implementation changes.

How to resolve common integration bugs

• Method not found (-32601): The client called a method the server doesn't implement. Fix: check the server's capability response during initialization.

• Invalid params (-32602): The arguments failed schema validation, usually a missing required field or type mismatch. Fix: log the params object and compare it to the tool's inputSchema.

• Internal error (-32603): The server encountered a failure during execution. In practice this often points to an upstream API issue or a credential problem. Fix: check server logs and verify credential validity.

Troubleshooting your MCP integration setup

Connectivity needs for MCP integrations

MCP defines two current transport types. Standard Input/Output (stdio) is for local connections, where the host spawns the server as a child process and communicates over stdin/stdout. No network ports are exposed, and the operating system's user permissions handle access control. Streamable HTTP is for remote connections, where the server runs independently and the client connects over HTTP, making it necessary when a centralized server needs to serve multiple clients. Note that Server-Sent Events (SSE) transport is deprecated in the current specification but remains widely supported in existing tools.

Bundling multiple tools per server

Composio's MCP Gateway consolidates multiple apps into a single endpoint. IT admins can whitelist or blacklist toolkits per team, review complete audit logs of every tool call, and manage access via SSO, all from one control surface. Each team gets a unique MCP endpoint that drops into Claude Desktop, Cursor, or any other MCP-compatible host without additional configuration.

How MCP handles private API keys

The standard local MCP setup can store API keys in configuration files on your machine. You must protect those files with strict permissions and keep them out of version control. Best practices recommend using environment variables or secure credential managers rather than storing secrets in plaintext files. Token refresh behaviour varies across MCP client implementations and is not standardised by the protocol itself. For a solo developer running two or three integrations, this is manageable. For a team running dozens in production, it becomes an ongoing operational problem.

Composio's managed auth layer handles OAuth 2.0, API keys, and JWT tokens across all supported apps, including Connect Link for mid-conversation user authorization. The platform is SOC 2 Type II certified, and its zero data retention (ZDR) mode stops Composio from retaining request and response payloads.

Handling unexpected MCP server outages

When a server goes down mid-session, the client receives a connection error or timeout. Use this process to recover cleanly:

1. Check transport connectivity first. For stdio, verify the server process is still running. For Streamable HTTP or SSE, confirm the HTTP endpoint is reachable.

2. Inspect server logs. Most MCP server implementations write errors to stderr, which the host captures. Look for API errors, credential failures, or uncaught exceptions.

3. Verify credential validity. Expired tokens are a common cause of silent failures after initial connection. Re-authorize the affected integration.

4. Re-establish connectivity. Once the server is healthy, send a fresh request — since the protocol is stateless, the server processes each request independently. Confirm the server is responding correctly by calling tools/list or server/discover and checking that it returns a valid tool catalog.

5. Set up monitoring for production. Treat MCP server availability the same way you'd treat any API dependency. Log connection events, alert on repeated failures, and consider a managed gateway to reduce the operational surface you're responsible for.

Start connecting your apps. Individual integrations like Gmail go live in under 30 minutes, giving Claude Desktop or any MCP-compatible agent access to 1,000+ pre-built tools with no local server configuration required.

FAQs

What is the Model Context Protocol?

MCP is a protocol Anthropic created in November 2024 that gives AI models a standardized way to discover and call external tools at runtime using JSON-RPC 2.0 messages. It defines a client-server architecture where the AI host dynamically learns what tools are available rather than relying on hardcoded integrations.

What is the difference between an MCP client, server, and host?

The host is the AI application (Claude Desktop, Cursor). The client is the component within the host that handles MCP protocol communication with servers. The server is a separate process that exposes tools, resources, and prompts to the client.

What transport protocols does MCP use?

MCP currently defines two primary transports: stdio for local connections, where the host spawns the server as a child process communicating over stdin/stdout, and Streamable HTTP for remote connections over HTTP. Server-Sent Events (SSE) is deprecated in the current specification but remains widely supported in existing tools.

How does the stateless MCP model handle session setup?

As of the 2026-07-28 specification, there is no handshake. The protocol is stateless — every request carries its own protocol version and capability flags in a _meta field, and the server evaluates each request independently. Tool discovery happens through an optional server/discover call or a tools/list request, with no prior session establishment required. This eliminates a class of failure where a dropped connection during initialization would block all subsequent tool calls.

How does tools/list differ from tools/call?

tools/list is a discovery call that returns the catalog of available tools with their schemas. tools/call is an execution call that triggers a specific tool with validated arguments and returns the result.

Is storing API keys in local MCP config files safe?

It's manageable for solo development but creates operational risk in production, since keys stored in plain text files must be manually protected, rotated, and kept out of version control. Composio's managed auth layer handles credential storage, OAuth refresh, and token custody automatically, with SOC 2 Type II certification covering the security layer.

How many tools does Composio offer compared to native MCP servers?

Composio exposes 1,000+ pre-built tools across major enterprise apps. A native Salesforce MCP server exposes just over 60 tools, while Composio's Salesforce toolkit exposes over 100 tools, each with LLM-optimized schemas and validated response formats.

Does Composio improve tool accuracy over time?

Yes. Composio's self-learning layer processes 300M+ tool calls per month and uses that signal to refine schema descriptions and parameter guidance continuously. In practice, this produces 30% better task accuracy compared to static schemas, while cutting token usage roughly in half, reducing both latency and API cost for production agent workflows.

Does MCP support event-driven triggers?

Many native MCP server implementations expose actions only, meaning an external process must initiate the agent workflow. Composio supports triggers alongside actions, so agents can respond to events (like a new email arriving or a Slack message matching a condition) without requiring a manual or externally initiated call.

Can I use Composio MCP with frameworks other than Claude Desktop?

Yes. Composio's MCP endpoint is compatible with any MCP-capable client, including Cursor, and works with AI frameworks like LangChain, CrewAI, LlamaIndex, Mastra, and AutoGen through provider packages that format tool schemas for each framework natively.

Terms glossary

MCP (Model Context Protocol): A protocol that defines how AI hosts, clients, and servers communicate, allowing models to discover and invoke external tools using JSON-RPC 2.0 messages at runtime.

JSON-RPC 2.0: A lightweight remote procedure call protocol that encodes requests and responses as JSON objects, each typically containing a method name, optional parameters, and an optional correlation ID.

Host: The AI application that manages the user session and owns the connection to one or more MCP servers, for example Claude Desktop or Cursor.

Client: The embedded protocol module inside the host that sends MCP requests, handles responses, and maintains session state with each connected server.

Server: A focused process that exposes tools, resources, and prompts through MCP primitives, executing real operations in external systems like Gmail, GitHub, or Salesforce.

stdio transport: A local MCP transport where the host spawns the server as a child process and communicates through the process's standard input and output streams.

Streamable HTTP transport: A remote MCP transport that uses HTTP POST and GET requests, enabling centralized servers to serve multiple clients over the network.

Capability negotiation: Under the 2026-07-28 specification, capability declaration is per-request rather than session-level. Each request carries a capabilities object inside its _meta field, telling the server what the client supports for that specific call. Servers expose available features through server/discover or in response to a tools/list request.

Tool Router: Composio's routing layer that inspects an incoming tool-call request and routes it to the correct toolkit based on the user's authenticated connections. This eliminates conditional logic in your agent code.

Zero data retention (ZDR): A Composio add-on available on Pro and above that prevents Composio from retaining request and response payloads, priced at $0.0001 per tool call and $0.0005 per trigger event.