> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt > Use this file to discover all available pages before exploring further. # MCP integration > Reference Model Context Protocol (MCP) tools by name in AgentMark prompts, then connect the servers at your own call site. AgentMark lets you reference Model Context Protocol (MCP) tools from your prompts. The prompt declares which server and tool it needs by name; **your runtime connects the server when it makes the model call.** The AgentMark client doesn't start MCP processes or open MCP connections. ## What's MCP? The **Model Context Protocol (MCP)** is an open standard that lets AI applications connect to external tools and data sources. Instead of hardcoding tool implementations, MCP lets you: * **Connect to tool servers**: use pre-built MCP servers for filesystems, databases, and APIs * **Standardize tool interfaces**: all MCP tools follow the same protocol, so they're interchangeable * **Share tools across projects**: one MCP server can serve multiple AI applications ## How MCP works with AgentMark 1. You **declare MCP servers by name** in `agentmark.json` so they're available in the Dashboard prompt editor. 2. You **reference MCP tools** in your prompt frontmatter using `mcp://{server}/{tool}` syntax. 3. The neutral render **surfaces those names**; it doesn't connect anything. 4. At your call site, **you connect the server** (with your SDK's MCP client, or inside an [executor](/getting-started/client-setup#connect-your-sdk)) and pass its tools into the model call. ```text theme={null} ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Your Prompt │────▶│ Neutral render │────▶│ Your call site │ │ mcp://fs/read │ │ (names only) │ │ connects fs │ └─────────────────┘ └─────────────────┘ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ MCP Server │ │ (filesystem) │ └─────────────────┘ ``` The AgentMark client surfaces the server names from `agentmark.json` and the tool names from frontmatter. Opening the connection is your runtime's responsibility, the same way [tool resolution](/build/tools-and-agents) happens at your call site rather than on the client. *** ## What you'll learn * Declare MCP servers by name in `agentmark.json` * Reference MCP tools in prompts using `mcp://` URIs * Combine MCP tools with other tool names * Connect the servers at your own call site *** ## 1) Declare MCP servers in `agentmark.json` List your MCP servers under `mcpServers` in `agentmark.json`. This makes them selectable in the Dashboard prompt editor and documents which servers your prompts expect. AgentMark supports two server types: | Type | Use case | Fields | | ----------- | ------------------------------------ | ------------------------------- | | **stdio** | Local tools that run as a subprocess | `command`, `args`, `cwd`, `env` | | **URL/SSE** | Remote tools accessed over HTTP | `url`, `headers` | ```json agentmark.json theme={null} { "mcpServers": { "docs": { "url": "https://docs.example.com/mcp" }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"] } } } ``` Server configuration rules: * URL servers accept only `url` and optional `headers`. * stdio servers accept only `command`, `args`, `cwd`, `env`. Servers declared in `agentmark.json` are available in the Dashboard prompt editor. They're **not** connected by the AgentMark client at runtime; your call site connects them when it makes the model call. ### `stdio` servers (local process) A stdio server runs as a child process on your machine, communicating over stdin/stdout. Use it for local development, accessing local files, or running custom tools. ### URL servers (remote HTTP) A URL server runs remotely and accepts requests over HTTP with Server-Sent Events (SSE). Use it for shared team tools, cloud-hosted services, and production deployments. *** ## 2) Reference MCP tools in prompts Declare MCP tools in your prompt frontmatter under `text_config.tools`. You can mix MCP tool names with other tool names: ```mdx mcp-example.prompt.mdx theme={null} --- name: mcp-example text_config: model_name: openai/gpt-5-mini tools: - mcp://docs/web-search - summarize --- Use the web-search tool to look up relevant documentation when needed. Use the summarize tool to condense content into a short summary. Find the page that explains MCP integration and summarize it in 2 sentences. ``` * `mcp://docs/web-search` names the MCP server `docs` and its tool `web-search`. * `summarize` names a regular tool you resolve at your call site. ### Wildcard: include all tools from a server Include every tool exported by a server using `*`: ```mdx theme={null} --- text_config: tools: - mcp://docs/* --- ``` * AgentMark includes all tools the `docs` server exports, under their original names. * If a tool name collides with an existing tool, resolve the conflict at your call site (the later-added tool typically wins). ## 3) Connect the server at your call site The neutral render gives you the requested tool names in `text_config.tools`. **You connect the MCP server with your own SDK's MCP client** and pass the server's tools into the model call. The exact connect helper belongs to your SDK, not to AgentMark. With the Vercel AI SDK, MCP support lives in the `@ai-sdk/mcp` package. You open the connection, fetch the tools, run the call, and close the connection: ```ts theme={null} import { client } from "./agentmark.client"; import { generateText, type ToolSet } from "ai"; import { createMCPClient } from "@ai-sdk/mcp"; import { openai } from "@ai-sdk/openai"; // You open the MCP connection — AgentMark does not. Match the server name // ("docs") to the entry in agentmark.json. const docsMcp = await createMCPClient({ transport: { type: "sse", url: process.env.AGENTMARK_MCP_SSE_URL! }, }); // Cast the tool set to the `ai` package's `ToolSet` so the two packages' // types line up. See the note below. const mcpTools = (await docsMcp.tools()) as ToolSet; const prompt = await client.loadTextPrompt("mcp-example.prompt.mdx"); const { messages, text_config } = await prompt.format({ props: {} }); const result = await generateText({ model: openai(text_config.model_name.replace(/^openai\//, "")), messages, tools: mcpTools, // merge with any locally-resolved tools by name }); await docsMcp.close(); console.log(result.text); ``` Use `createMCPClient` as the entry point. `@ai-sdk/mcp` pins an exact `@ai-sdk/provider-utils` version, which can differ from the one your installed `ai` resolves, so `mcp.tools()` doesn't always line up with `generateText`'s `ToolSet` under TypeScript's `strict` mode. Casting with `as ToolSet` bridges the version gap; the runtime tool shape is compatible. Pin compatible versions and consult the [Vercel AI SDK MCP docs](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling#mcp-tools) for the current API. For a stdio server, use the stdio transport instead of the SSE config. It's exported from the `@ai-sdk/mcp/mcp-stdio` subpath, not the package root: ```ts theme={null} import { createMCPClient } from "@ai-sdk/mcp"; import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio"; const fsMcp = await createMCPClient({ transport: new Experimental_StdioMCPTransport({ command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"], }), }); ``` To package this connection logic so AgentMark Cloud can run the prompt too, move it into an [executor](/getting-started/client-setup#connect-your-sdk): open the MCP client inside the executor's `text` handler and close it when the call returns. See [Connect your SDK](/getting-started/client-setup#connect-your-sdk) for the executor and serving pattern, and [Tools and agents](/build/tools-and-agents) for the resolve-by-name pattern that handles non-MCP tools the same way. ## Notes and best practices * Keep server configs minimal. URL servers need only `url`; stdio servers need only `command`. * Declare servers by name in `agentmark.json` so they appear in the Dashboard editor, but remember the AgentMark client doesn't connect them. * Connect each server once at your call site and reuse the connection across calls where you can; close stdio/SSE connections when you're done. * Use a wildcard reference (`mcp://server/*`) to expose a server's full tool surface, but watch for name collisions when you merge tool sets at your call site.

Have questions?

Reach out any time: