MCP integration - AgentMark Docs

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

You declare MCP servers by name in agentmark.json so they’re available in the Dashboard prompt editor.
You reference MCP tools in your prompt frontmatter using mcp://{server}/{tool} syntax.
The neutral render surfaces those names; it doesn’t connect anything.
At your call site, you connect the server (with your SDK’s MCP client, or inside an executor) and pass its tools into the model call.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  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 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`

agentmark.json

{
  "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:

mcp-example.prompt.mdx

---
name: mcp-example
text_config:
  model_name: openai/gpt-5-mini
  tools:
    - mcp://docs/web-search
    - summarize
---

<System>
Use the web-search tool to look up relevant documentation when needed.
Use the summarize tool to condense content into a short summary.
</System>

<User>
Find the page that explains MCP integration and summarize it in 2 sentences.
</User>

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 *:

---
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:

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 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:

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: open the MCP client inside the executor’s text handler and close it when the call returns. See Connect your SDK for the executor and serving pattern, and 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:

Email the team at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about AgentMark’s business solutions

​What’s MCP?

​How MCP works with AgentMark

​What you’ll learn

​1) Declare MCP servers in agentmark.json

​stdio servers (local process)

​URL servers (remote HTTP)

​2) Reference MCP tools in prompts

​Wildcard: include all tools from a server

​3) Connect the server at your call site

​Notes and best practices

​Have questions?

What’s MCP?

How MCP works with AgentMark

What you’ll learn

1) Declare MCP servers in `agentmark.json`

`stdio` servers (local process)

URL servers (remote HTTP)

2) Reference MCP tools in prompts

Wildcard: include all tools from a server

3) Connect the server at your call site

Notes and best practices

Have questions?