# mcp

the model context protocol. an open standard for connecting ai models (hosts) to external systems (servers) via structured tools, resources, and prompts. it acts as a "usb-c port for ai."

## architecture

mcp defines a client-server relationship:

- **host**: the ai application (e.g., claude code, vscode) that coordinates and manages mcp clients.
- **client**: maintains a dedicated connection to an mcp server and obtains context from it for the host. a host can have multiple clients.
- **server**: a program that provides context (tools, resources, prompts) to mcp clients. servers can run locally (stdio) or remotely (http/sse).

```
┌─────────────┐     ┌─────────────┐
│  MCP Host   │     │ MCP Server  │
│ (LLM Client)│─────│ (Tools, Data)│
└──────┬──────┘     └─────────────┘
       │                 ▲
       │ request/response│
       │                 │
       │ context, actions│
       ▼                 │
┌─────────────┐     ┌─────────────┐
│  MCP Client │─────│  External   │
│ (Per Server)│     │  System     │
└─────────────┘     └─────────────┘
```

## primitives

mcp servers expose three core primitives:

### tools
executable functions that the host (via the llm) can invoke.
- define actions an ai can take.
- typically correspond to python functions with type hints and docstrings.
- examples: `add_event_to_calendar(title: str, date: str)`, `search_docs(query: str)`.

### resources
read-only data sources exposed to the host.
- content is addressed by a uri (e.g., `config://app/settings.json`, `github://repo/readme.md`).
- can be structured (json) or unstructured (text, binary).
- examples: application configuration, documentation, database entries.

### prompts
reusable templates for interaction.
- define common interactions or workflows.
- can guide the llm in complex tasks.
- examples: `summarize_document(document: str)`, `generate_report(data: dict)`.

## transport

mcp supports flexible transport mechanisms:
- **stdio**: standard input/output. efficient for local, co-located processes.
- **streamable http**: for remote servers. uses http post for client messages and server-sent events (sse) for streaming responses. supports standard http auth.

## applications & patterns

### plyr.fm mcp server
an mcp server that exposes a music library (plyr.fm) to llm clients.
- **purpose**: allows llms to query track information, search the library, and get user-specific data (e.g., liked tracks).
- **design**: primarily **read-only** tools (e.g., `list_tracks`, `get_track`, `search`). mutations are handled by a separate cli.
- **source**: [zzstoatzz/plyr-python-client](https://github.com/zzstoatzz/plyr-python-client/tree/main/packages/plyrfm-mcp)

### prefect mcp server
an mcp server for interacting with prefect, a workflow orchestration system.
- **purpose**: enables llms to monitor and manage prefect workflows.
- **design**: exposes monitoring tools (read-only) and provides guidance for **mutations** via the prefect cli.
- **pattern**: emphasizes "agent-friendly usage" of the prefect cli, including `--no-prompt` and `prefect api` for json output, to facilitate programmatic interaction by llms.
- **source**: [prefecthq/prefect-mcp-server](https://github.com/PrefectHQ/prefect-mcp-server)

## ecosystem

- [fastmcp](./fastmcp.md) - pythonic server framework
- [oauth](./oauth.md) - auth for remote mcp servers: flows, jwks verification, consent scoping
- [claude-code-plugins](./claude-code-plugins.md) - packaging servers + skills for claude code
- [pdsx](https://github.com/zzstoatzz/pdsx) - mcp server for atproto
- [inspector](https://github.com/modelcontextprotocol/inspector) - web-based debugger for mcp servers

## sources

- [modelcontextprotocol.io](https://modelcontextprotocol.io) - official documentation
- [jlowin/fastmcp](https://github.com/jlowin/fastmcp) - the fastmcp python library