about things
1# mcp
2
3the 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."
4
5## architecture
6
7mcp defines a client-server relationship:
8
9- **host**: the ai application (e.g., claude code, vscode) that coordinates and manages mcp clients.
10- **client**: maintains a dedicated connection to an mcp server and obtains context from it for the host. a host can have multiple clients.
11- **server**: a program that provides context (tools, resources, prompts) to mcp clients. servers can run locally (stdio) or remotely (http/sse).
12
13```
14┌─────────────┐ ┌─────────────┐
15│ MCP Host │ │ MCP Server │
16│ (LLM Client)│─────│ (Tools, Data)│
17└──────┬──────┘ └─────────────┘
18 │ ▲
19 │ request/response│
20 │ │
21 │ context, actions│
22 ▼ │
23┌─────────────┐ ┌─────────────┐
24│ MCP Client │─────│ External │
25│ (Per Server)│ │ System │
26└─────────────┘ └─────────────┘
27```
28
29## primitives
30
31mcp servers expose three core primitives:
32
33### tools
34executable functions that the host (via the llm) can invoke.
35- define actions an ai can take.
36- typically correspond to python functions with type hints and docstrings.
37- examples: `add_event_to_calendar(title: str, date: str)`, `search_docs(query: str)`.
38
39### resources
40read-only data sources exposed to the host.
41- content is addressed by a uri (e.g., `config://app/settings.json`, `github://repo/readme.md`).
42- can be structured (json) or unstructured (text, binary).
43- examples: application configuration, documentation, database entries.
44
45### prompts
46reusable templates for interaction.
47- define common interactions or workflows.
48- can guide the llm in complex tasks.
49- examples: `summarize_document(document: str)`, `generate_report(data: dict)`.
50
51## transport
52
53mcp supports flexible transport mechanisms:
54- **stdio**: standard input/output. efficient for local, co-located processes.
55- **streamable http**: for remote servers. uses http post for client messages and server-sent events (sse) for streaming responses. supports standard http auth.
56
57## applications & patterns
58
59### plyr.fm mcp server
60an mcp server that exposes a music library (plyr.fm) to llm clients.
61- **purpose**: allows llms to query track information, search the library, and get user-specific data (e.g., liked tracks).
62- **design**: primarily **read-only** tools (e.g., `list_tracks`, `get_track`, `search`). mutations are handled by a separate cli.
63- **source**: [zzstoatzz/plyr-python-client](https://github.com/zzstoatzz/plyr-python-client/tree/main/packages/plyrfm-mcp)
64
65### prefect mcp server
66an mcp server for interacting with prefect, a workflow orchestration system.
67- **purpose**: enables llms to monitor and manage prefect workflows.
68- **design**: exposes monitoring tools (read-only) and provides guidance for **mutations** via the prefect cli.
69- **pattern**: emphasizes "agent-friendly usage" of the prefect cli, including `--no-prompt` and `prefect api` for json output, to facilitate programmatic interaction by llms.
70- **source**: [prefecthq/prefect-mcp-server](https://github.com/PrefectHQ/prefect-mcp-server)
71
72## ecosystem
73
74- [fastmcp](./fastmcp.md) - pythonic server framework
75- [pdsx](https://github.com/zzstoatzz/pdsx) - mcp server for atproto
76- [inspector](https://github.com/modelcontextprotocol/inspector) - web-based debugger for mcp servers
77
78## sources
79
80- [modelcontextprotocol.io](https://modelcontextprotocol.io) - official documentation
81- [jlowin/fastmcp](https://github.com/jlowin/fastmcp) - the fastmcp python library