What is an MCP server, in plain terms

A model can only act through something you gave it. Every product that wanted an assistant integration used to ship its own connector, with its own auth, its own error shapes, and its own idea of what a tool call looks like. Each new client meant another integration.

MCP fixes the shape rather than the feature. A server declares what it can do in a standard format, a client discovers that declaration, and the model picks from it. The same Datadef server answers Claude Code, Cursor, VS Code, Claude Desktop, Codex, Gemini CLI, and ChatGPT without a client-specific build.

Three kinds of thing: tools, which the model can call; prompts, which are reusable instructions a user can invoke; and resources, which are readable content. Tools are where nearly all the value sits today, because clients surface them reliably and prompts less so.

A concrete inventory helps. The Datadef server publishes 36 tools. Nine operate on whole diagrams: get_design_guide, create_diagram, create_blank_diagram, list_diagrams, get_diagram, edit_diagram, export_diagram, repo_status, repo_refresh. The other 27 are canvas operations, prefixed canvas_, covering nodes, edges, zones, column lineage, layout, measurement, and validation. There is also one prompt, datadef_design_guide, carrying the same design standard as the tool version, because many clients never show prompts to the model.

The interesting one is not a drawing tool. get_design_guide returns the size, edge, and zone standard that the in-app generator follows, so an agent that reads it first produces something indistinguishable from a generated diagram, and an agent that skips it produces exactly what the standard exists to prevent.

Servers come in two transports. Local ones run as a process on your machine and speak over stdio. Remote ones are an HTTP endpoint you point a client at, with a bearer token for auth. Datadef is remote: a Streamable HTTP endpoint at https://datadef.io/mcp. Desktop clients that only speak stdio bridge to it through the mcp-remote package, which forwards the Authorization header.

Discovery does not require credentials on this server. Seven JSON-RPC methods answer without a key: initialize, notifications/initialized, ping, tools/list, prompts/list, resources/list, and resources/templates/list. None of them executes anything or reads user data. tools/call is the one that still returns 401.

That split is worth knowing if you ever publish a server. Directory crawlers and registry health checks run in containers with no credentials, and while initialize sat behind auth they recorded the server as having zero tools. Opening the handshake and the listings is what lets a scorer, or a curious agent, read the whole tool surface before a key exists.

# See what a remote MCP server offers, before connecting anything
curl -s https://datadef.io/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# -> 36 tools, with descriptions and input schemas.
# tools/call without a bearer token returns 401.

It is not a background job system. A tool runs when a model calls it inside a live session, and nothing continues after the session ends. An MCP server cannot watch your repository, notice a merge, or wake up on a schedule, and any product describing that behaviour is doing it with something other than MCP. At Datadef that something is repository sync, which regenerates connected diagrams daily on its own.

It is also not a data pipeline into the model. The server sees the arguments of the calls it receives and nothing else. A diagram server that has no tool accepting source files never receives source files, whatever the client happens to have open.

• MCP server documentation and client setup
• Draw diagrams with your AI agent over MCP
• Connect Claude Code to a diagram tool
• An MCP server for architecture diagrams