mcpc-core

name	mcpc-core
description	Build agentic MCP servers using @mcpc/core by composing existing MCP tools. Use when creating, extending, or debugging MCPC agentic servers — including setting up compositions, choosing execution modes, writing plugins, loading skills, and connecting transports.

@mcpc/core — Build Agentic MCP Servers

@mcpc/core lets you compose existing MCP tools into agentic MCP tools. You write a description that references tools via <tool> XML tags, and MCPC wires everything up into a working MCP server.

Installation

# Deno (preferred in this repo)
deno add jsr:@mcpc/core

# npm
npm install @mcpc-tech/core

# pnpm (from JSR)
pnpm add jsr:@mcpc/core

Minimal Example

import { mcpc } from "@mcpc/core";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await mcpc(
  [{ name: "my-agent", version: "1.0.0" }, { capabilities: { tools: {} } }],
  [{
    name: "file-agent",
    description: `I help manage files.
Available tools:
<tool name="@wonderwhy-er/desktop-commander.read_file"/>
<tool name="@wonderwhy-er/desktop-commander.write_file"/>`,
    deps: {
      mcpServers: {
        "@wonderwhy-er/desktop-commander": {
          command: "npx",
          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
          transportType: "stdio",
        },
      },
    },
  }],
);

await server.connect(new StdioServerTransport());

Core API

mcpc(serverConf, composeConf?, options?)

Param	Type	Description
serverConf	[ServerMeta, ServerCapabilities]	Name/version + capabilities tuple
composeConf	ComposeInput[]	Array of ComposeDefinition objects or .md file paths
options	McpcOptions	Loader plugins + setup callback

Returns Promise<ComposableMCPServer>.

ComposeDefinition

{
  name: string | null,          // null = composition-only (no tool exposed)
  description?: string,         // Natural language + <tool> XML refs
  manual?: string,              // Progressive disclosure: long docs hidden behind man tool
  deps?: MCPSetting,            // Dependent MCP servers to connect
  plugins?: (ToolPlugin | string)[],  // Runtime plugins
  options?: {
    mode?: "agentic" | "ai_sampling" | "ai_acp",  // default: "agentic"
    maxSteps?: number,          // default: 50
    maxTokens?: number,         // default: 128_000 (ai_sampling only)
    samplingConfig?: SamplingConfig,
    providerOptions?: { modelPreferences?: {...} },  // ai_sampling only
    acpSettings?: { command, args, env, session, persistSession },  // ai_acp only
    tracingEnabled?: boolean,   // OpenTelemetry
    refs?: ToolRefXml[],
  }
}

Tool References (<tool> XML)

In the description field, reference tools with XML tags:

<tool name="server.tool_name"/>              — specific tool
<tool name="server.__ALL__"/>               — all tools from a server
<tool name="server.tool" maxResultLength="2000"/>  — truncate large results
<tool name="server.tool" hide/>             — use internally, hide from public API
<tool name="server.tool" global/>           — expose at top-level scope

MCP Server Dependencies (deps.mcpServers)

Three transport types:

// stdio
"my-server": { command: "npx", args: ["-y", "pkg@latest"], transportType: "stdio" }

// Streamable HTTP
"remote": { transportType: "streamable-http", url: "https://api.example.com/mcp/",
            headers: { "Authorization": "Bearer ${TOKEN}" } }

// SSE
"sse-server": { transportType: "sse", url: "https://api.example.com/sse/" }

Execution Modes

Mode	Description	Best For
agentic	Fully autonomous, uses MCP sampling	Default; most flexible
ai_sampling	Uses AI SDK streamText + MCP sampling provider	When you control the model
ai_acp	AI SDK + ACP protocol for coding agents	Claude Code, Codex-style agents

Plugins

Built-in Plugins (import from @mcpc/core/plugins)

import {
  createBashPlugin, // Add bash execution tool
  createLargeResultPlugin, // Truncate/paginate large tool results
  createSearchPlugin, // Add ripgrep-based search tool
  createSkillsPlugin, // Lazy-load skill knowledge
} from "@mcpc/core/plugins";

Using Plugins

// In ComposeDefinition
plugins: [
  createLargeResultPlugin({ maxSize: 8000 }),
  createSkillsPlugin({ paths: [".agents/skills"] }),
  createBashPlugin(),
  "./my-plugin.ts?param=value", // File path with query params
];

// Or in mcpc() options (loader plugins, run before composition)
await mcpc(serverConf, composeConf, {
  plugins: ["@mcpc/plugin-markdown-loader"],
});

Writing a Custom Plugin (ToolPlugin)

import type { ToolPlugin } from "@mcpc/core";

const myPlugin: ToolPlugin = {
  name: "my-plugin",

  // Mutate/filter tool descriptions at compose time
  transformTool?: (tool: ComposedTool, ctx: TransformContext) => ComposedTool,

  // Intercept inputs before execution
  transformInput?: (args: unknown, ctx: BeforeToolExecuteContext) => unknown,

  // Intercept outputs after execution
  transformOutput?: (result: unknown, ctx: AfterToolExecuteContext) => unknown,

  // Lifecycle hooks
  onComposeStart?: (ctx: ComposeStartContext) => void,
  onComposeEnd?: (ctx: ComposeEndContext) => void,
  onFinalize?: (ctx: FinalizeContext) => void,
};

Skills Plugin

createSkillsPlugin adds a {agent}__load-skill tool that lazy-loads skill content:

createSkillsPlugin({
  paths: [join(projectRoot, ".agents/skills")],
});

Skills directory structure:

.agents/skills/
└── my-skill/
    ├── SKILL.md          ← main instructions (loaded by default)
    └── references/
        └── api.md        ← loaded via { skill, ref: "references/api.md" }

Agent calls:

agent__load-skill({ skill: "my-skill" })
agent__load-skill({ skill: "my-skill", ref: "references/api.md" })

Markdown Agent Files

Load agent definitions from .md files (requires @mcpc/plugin-markdown-loader):

await mcpc(
  [{ name: "server", version: "1.0.0" }, { capabilities: { tools: {} } }],
  ["./agents/my-agent.md"],
  { plugins: ["@mcpc/plugin-markdown-loader"] },
);

Markdown format:

---
name: my-agent
deps:
  mcpServers:
    some-server:
      command: npx
      args: ["-y", "some-server"]
      transportType: stdio
options:
  mode: agentic
---

I am an agent that does X.

<tool name="some-server.tool"/>

Setup Callback (Custom Tools)

Register tools directly on the server before composition:

import { jsonSchema } from "@mcpc/core";

await mcpc(serverConf, composeConf, {
  setup: async (server) => {
    server.tool(
      "my-tool",
      "Description of tool",
      jsonSchema({ type: "object", properties: { input: { type: "string" } } }),
      async (args) => ({
        content: [{ type: "text", text: `Got: ${args.input}` }],
      }),
    );
    await server.addPlugin(myPlugin);
  },
});

Gotchas

• transportType is required in every mcpServers entry — omitting it causes a silent failure.
• name: null in ComposeDefinition skips creating the composed tool; useful for composition-only (just wiring up deps + plugins).
• Plugin load order matters: McpcOptions.plugins run before composition (use for loaders). ComposeDefinition.plugins run after composition (use for runtime transforms).
• hide vs global on <tool>: hide keeps a tool internal to the agent. global exposes it at top-level without a namespace prefix.
• manual field: if set, description becomes a short summary and full content is behind a man tool call — reduces initial context size.
• Environment variables in headers: use ${VAR_NAME} syntax inside strings in deps.mcpServers[*].headers — MCPC expands them at runtime.
• maxSteps default is 50 for ai_sampling/ai_acp modes — increase for complex multi-step tasks.

References

• See references/examples.md for complete working examples
• Source: https://github.com/mcpc-tech/mcpc/tree/main/packages/core
• Docs: https://github.com/mcpc-tech/mcpc/tree/main/docs