@archships/dim-plugin-mcp-client

Official MCP client plugin for dim-agent-sdk, backed by the upstream @modelcontextprotocol/sdk.

Requires @archships/dim-agent-sdk >= 0.0.20 and @archships/dim-plugin-api >= 0.0.7 so the published plugin matches the current official runtime and plugin-contract floors. The workspace package also keeps @archships/dim-agent-sdk and @archships/dim-plugin-api as workspace:* dev dependencies for local development.

What it does

• exposes a session-scoped controller through session.getPlugin('mcp-client')
• connects to real MCP servers on demand
• discovers MCP tools immediately when connectServer() succeeds
• exposes discovered tools as <serverId>__<toolName>
• executes tool calls against the real MCP server
• keeps compatibility support for host-provided tools and promptSegments

Current scope:

• tools only
• supported transports: stdio, streamable-http
• resources, prompts, and sampling are not part of this plugin yet

Usage

import { createAgent, createModel } from '@archships/dim-agent-sdk'
import {
  createMcpClientPlugin,
  type McpClientSessionController,
} from '@archships/dim-plugin-mcp-client'

const agent = createAgent({
  model: createModel(adapter),
  plugins: [createMcpClientPlugin({ transports: ['stdio'] })],
})

const session = await agent.createSession()
const mcp = session.getPlugin<McpClientSessionController>('mcp-client')

await mcp?.connectServer({
  id: 'everything',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-everything'],
})

For Streamable HTTP:

const agent = createAgent({
  model: createModel(adapter),
  plugins: [createMcpClientPlugin({ transports: ['streamable-http'] })],
})

const session = await agent.createSession()
const mcp = session.getPlugin<McpClientSessionController>('mcp-client')

await mcp?.connectServer({
  id: 'everything-http',
  transport: 'streamable-http',
  url: 'http://127.0.0.1:3001/mcp',
})

Compatibility-only host injection is still available:

createMcpClientPlugin({
  tools: [mcpTool],
  promptSegments: ['MCP prompt contribution.'],
})

Controller behavior

• getState(): returns { servers } for the current session only
• connectServer(server): validates transport access, connects immediately, discovers tools immediately, and throws on failure
• disconnectServer(serverId): closes that session's MCP connection and removes its tools; missing ids are a no-op

Notes

• configure transports at plugin creation time only to declare static permissions
• stdio requires process; streamable-http requires network
• required is no longer part of the public API; connection failures throw from connectServer()
• MCP server config is session-local, in-memory only, and is not restored from snapshots
• dispose the session or agent with await session.dispose() / await agent.dispose() when the process is done, so MCP connections and child processes are released
• manual smoke examples:
  • stdio server:

    await mcp?.connectServer({
      id: 'everything',
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-everything'],
    })

  • Streamable HTTP:

    npx @modelcontextprotocol/server-everything streamableHttp