For engineers integrating tools

What is MCP (Model Context Protocol), and how to build an MCP server

What MCP is

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context and tools to large language models. It is maintained as a public specification (see modelcontextprotocol.io) and is implemented by a growing set of clients and servers.

Before a standard like this, every team wired its own bridge between a model and its tools: a custom adapter for the database, another for the ticketing system, another for the file store, each tied to one app. MCP collapses that into a single interface. A server advertises what it offers; a client discovers those capabilities at runtime and uses them. The integration is written once, against the protocol, rather than once per pairing.

The three primitives

MCP organizes what a server exposes into three primitives. Keeping them distinct matters because clients and models treat them differently.

Tools

Model-callable functions with typed inputs. A tool is something the model can decide to invoke - run a query, send a message, create a record - with arguments described by a JSON schema so the client knows what is valid.

Resources

Data and content the model can read. Resources are addressable pieces of context - a document, a file, a record - that a client can pull in and hand to the model, rather than actions the model takes.

Prompts

Reusable prompt templates. A server can publish parameterized prompts that clients surface to users or feed to the model, so common workflows do not have to be re-authored in every app.

MCP vs an API

They sit at different layers: an API is the underlying service that does the work, and MCP is a standardized, discoverable interface on top of it, which is why an MCP server usually wraps an existing API rather than replacing it. See MCP vs API for the full dimension-by-dimension comparison and when to use each.

MCP also only standardises one layer of an agent system — the tools and action layer. Orchestration, memory, retrieval, and the operational plane are separate components with their own decisions; agentic AI architecture maps all six, including the reasoning core, and shows where a server plugs in.

MCP servers in the wild: AWS, GitHub, and more

You do not always have to write a server from scratch. A growing ecosystem of first-party and vendor-shipped MCP servers already exists, so an agent can reach a major platform without you authoring any glue. Two of the most widely used are GitHub's official server and AWS Labs' suite.

GitHub's official server (github/github-mcp-server) is the canonical example of a vendor-shipped MCP server. It lets an agent work with repositories, issues, pull requests, and code - browsing files, triaging and managing issues and PRs, and reasoning over a project's structure. It ships two ways: a GitHub-hosted remote endpoint with OAuth, and a local Docker container you run yourself (useful for self-hosted or GitHub Enterprise setups).

AWS Labs publishes an open-source collection of MCP servers (awslabs/mcp) - several of them, covering documentation lookup, infrastructure as code (CloudFormation and CDK), cost analysis, Bedrock Knowledge Bases retrieval, and access to core AWS services - that let an agent reason over your AWS environment. Some, like the AWS Knowledge server, are AWS-hosted managed services rather than packages you run locally.

Exact tool names and the set of available servers change as these projects evolve - check each repository for the current list before you rely on a specific capability.

Reaching for an existing server is the fast path when one exists for your platform. When you need to expose your own systems instead, see how to build an MCP server, step by step - and if you are still deciding whether you even need a server, MCP vs API covers when each layer is the right tool.

How to build an MCP server

The shape of a server is consistent even though exact function names and types evolve: define your tools with typed inputs, implement the handlers, expose resources and prompts as needed, validate every input under least privilege, then connect a client and test both discovery and execution. The step-by-step build, with working Python code for each step, starts from scaffolding a server with the official SDK.

Security

Tools are an attack surface. The moment a model can take an action, a bad or manipulated input can take that action too. Treat every server with the same caution you would any system that executes on behalf of an untrusted caller: least privilege on what each tool can reach, strict input validation, and human-in-the-loop confirmation on irreversible actions.

Prompt injection makes this concrete - content a model reads can try to steer the tools it calls. Scope credentials tightly, validate before acting, and require explicit approval for anything you cannot easily undo.

As-built: this site is itself an MCP client

The coach on aiarch.dev is a live MCP client, not just a description of what one is. src/lib/docsMcp.ts calls the public, no-auth aws-knowledge and cloudflare-docs MCP servers directly over Streamable HTTP whenever the model decides a question needs a current documentation lookup — the same servers configured in this repo's own .mcp.json for Claude Code's use, called here by a second, independent client.

The two providers do not encode their tool responses the same way, which is the part no spec page tells you and you only learn by calling both. Cloudflare's server always replies as Server-Sent Events, even for a single one-shot tools/call with no session established — the result has to be pulled out of the SSE data: line before it is even JSON, and the tool's own content is pseudo-XML result blocks rather than a JSON object. AWS's server replies plain JSON, but double-encodes: the MCP response's text field is itself a JSON string, so it needs a second parse to reach the actual document hits. Neither server requires the initialize handshake or an Mcp-Session-Id that a stateful MCP session implies, for a single call — the 2025-11-25 revision does not say either way, so it had to be confirmed by calling both endpoints directly. Revision 2026-07-28, published on that date, settles it in the same direction and goes further: it removes the handshake and protocol-level sessions outright, and requires Mcp-Method and MCP-Protocol-Version on every POST plus Mcp-Name on the calls that name a target — tools/call, resources/read and prompts/get — with two _meta fields in the body on top. Neither omission is a silent downgrade, and they fail differently: a missing header is 400 with JSON-RPC -32020 HeaderMismatch, while a missing _meta field is 400 with -32602, so adding the headers and stopping still leaves you non-compliant. Measured against both servers on 28 Jul 2026, each returns a 200 with real results for either shape — so this client sends the newer one and falls back once, on a 400, to the older. Pinning either era outright is the actual hazard: as of 3 Aug 2026 the versioning page names 2026-07-28 current and 2025-11-25 is Final — complete and unchanging, not deprecated — so a server that speaks only that one is still conformant, because every request declares its own protocol version and the server accepts or rejects each one independently. AWS also enforces an undocumented roughly one-request-per-15-second per-IP limit, so the client makes one soft-failing attempt per lookup rather than backing off and hammering it; that 400 fallback is the only second request it will ever send. callMcpTool never throws either way — a network failure or a malformed response returns an empty result with a reason, so the coach can tell the learner a live lookup failed instead of guessing. It is the "connect a client and test both discovery and execution" step above, done against two real vendor servers instead of one you control.