@elsium-ai/mcp

Model Context Protocol (MCP) support for ElsiumAI — bidirectional client and server over stdio transport.

Install

npm install @elsium-ai/mcp

Peer dependencies @elsium-ai/core and @elsium-ai/tools are pulled in automatically when you install within the ElsiumAI monorepo. In standalone usage, install them explicitly:

npm install @elsium-ai/mcp @elsium-ai/core @elsium-ai/tools

What’s Inside

Client

MCPClientConfig

MCPClientConfig is a discriminated union over the transport field, with one variant per transport. createMCPClient selects the implementation based on transport.

type MCPClientConfig = MCPClientStdioConfig | MCPClientHttpConfig

MCPClientStdioConfig — connect to a server spawned as a child process:

interface MCPClientStdioConfig {
  name: string            // Client identifier
  transport: 'stdio'      // Transport discriminant
  command: string         // Command to spawn the server process
  args?: string[]         // Command arguments
  env?: Record<string, string>  // Environment variables for the process
  timeoutMs?: number      // Request timeout (default: 30000)
}

MCPClientHttpConfig — connect to a server over HTTP JSON-RPC:

interface MCPClientHttpConfig {
  name: string            // Client identifier
  transport: 'http'       // Transport discriminant
  url: string             // Server endpoint URL
  headers?: Record<string, string>  // Extra headers sent with every request
  timeoutMs?: number      // Request timeout (default: 30000)
}

MCPToolInfo

Describes a single tool as reported by an MCP server’s tools/list response.

interface MCPToolInfo {
  name: string
  description: string
  inputSchema: Record<string, unknown>
}

MCPClient

The interface returned by createMCPClient. Provides methods for connecting to an MCP server, discovering its tools, calling them, and converting them into ElsiumAI-compatible Tool objects.

interface MCPClient {
  connect(): Promise<void>
  disconnect(): Promise<void>
  listTools(): Promise<MCPToolInfo[]>
  callTool(name: string, args: Record<string, unknown>): Promise<unknown>
  toElsiumTools(): Promise<Tool[]>
  listResources(): Promise<MCPResource[]>
  readResource(uri: string): Promise<MCPResourceContent[]>
  listPrompts(): Promise<MCPPrompt[]>
  getPrompt(name: string, args?: Record<string, string>): Promise<MCPPromptMessage[]>
  readonly connected: boolean
}

createMCPClient(config)

Create a new MCP client. The client does not connect automatically — call connect() before using it.

function createMCPClient(config: MCPClientConfig): MCPClient

Parameters

Returns — MCPClient

Example — connect to an MCP server and list its tools

import { createMCPClient } from '@elsium-ai/mcp'

const client = createMCPClient({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
})

await client.connect()

const tools = await client.listTools()
console.log(tools)
// [{ name: 'read_file', description: '...', inputSchema: { ... } }, ...]

await client.disconnect()

Example — call a remote tool directly

import { createMCPClient } from '@elsium-ai/mcp'

const client = createMCPClient({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
})

await client.connect()

const content = await client.callTool('read_file', { path: '/tmp/hello.txt' })
console.log(content) // file contents as a string

await client.disconnect()

Example — convert MCP tools into ElsiumAI tools for an agent

import { createMCPClient } from '@elsium-ai/mcp'

const client = createMCPClient({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
})

await client.connect()

// Each returned Tool has execute() and toDefinition() wired through the MCP client
const elsiumTools = await client.toElsiumTools()

// Pass them to an agent, a toolkit, or call execute() directly
const result = await elsiumTools[0].execute({ path: '/tmp/hello.txt' })
console.log(result)
// { success: true, data: '...', toolCallId: 'tc_...', durationMs: 42 }

Server

MCPServerConfig

Configuration object passed to createMCPServer.

interface MCPServerConfig {
  name: string                       // Server name
  version?: string                   // Server version
  tools: Tool[]                      // ElsiumAI tools to expose via MCP
  resources?: MCPResourceHandler[]   // Resources to expose via MCP
  prompts?: MCPPromptHandler[]       // Prompt templates to expose via MCP
}

MCPServer

The interface returned by createMCPServer. The server reads JSON-RPC requests from stdin and writes responses to stdout, implementing the MCP protocol over stdio transport.

interface MCPServer {
  start(): Promise<void>
  stop(): void
  readonly running: boolean
}

createMCPServer(config)

Create a new MCP server that exposes the provided ElsiumAI tools over the MCP protocol.

function createMCPServer(config: MCPServerConfig): MCPServer

Parameters

Returns — MCPServer

Example — expose ElsiumAI tools as an MCP server

import { createMCPServer } from '@elsium-ai/mcp'
import { createTool } from '@elsium-ai/tools'
import { z } from 'zod'

const greet = createTool({
  name: 'greet',
  description: 'Return a greeting for the given name',
  input: z.object({ name: z.string() }),
  execute: async ({ input }) => `Hello, ${input.name}!`,
})

const server = createMCPServer({
  name: 'my-tools',
  version: '1.0.0',
  tools: [greet],
})

await server.start()
// The server is now listening on stdin/stdout.
// MCP clients (e.g. Claude Desktop) can connect to it via stdio transport.

Types

MCP Trust Framework

Security layer for MCP connections: server allowlists, tool filtering, output validation, manifest integrity, and audit logging.

createTrustedMCPClient

createTrustedMCPClient(config: MCPClientConfig, trustConfig: MCPTrustConfig): TrustedMCPClient

Wraps a standard MCP client with security controls.

MCPTrustConfig:

AllowedServer:

import { createTrustedMCPClient } from '@elsium-ai/mcp'

const client = createTrustedMCPClient(
  { name: 'data-tools', transport: 'http', url: 'http://localhost:3001/mcp' },
  {
    allowedServers: [
      {
        name: 'data-tools',
        transport: 'http',
        urlPattern: '^http://localhost:3001',
        allowedTools: ['query_db', 'list_tables'],
        deniedTools: ['drop_table'],
      },
    ],
    maxToolOutputSize: 512 * 1024,
    auditLog: { log: (event) => console.log(event) },
  },
)

await client.connect()
const tools = await client.listTools() // only returns allowed tools

Tool Manifests

Generate and verify tool manifests for supply chain integrity:

const manifest = await client.generateManifest()
// { serverName, tools: [{ name, description, inputSchemaHash }], hash }

const isValid = await client.verifyManifest(manifest)
// false if server tools have changed since manifest was generated

Types

Resources & Prompts

Beyond tools, an MCP server may expose resources (readable data sources identified by URI) and prompts (named, parameterized message templates). A connected MCPClient can list and read them:

// Resources
const resources = await client.listResources()
// => [{ uri: 'file:///docs/readme.md', name: 'README', mimeType: 'text/markdown' }, ...]

const contents = await client.readResource('file:///docs/readme.md')
// => [{ uri: 'file:///docs/readme.md', mimeType: 'text/markdown', text: '# ...' }]

// Prompts
const prompts = await client.listPrompts()
// => [{ name: 'summarize', description: '...', arguments: [{ name: 'topic', required: true }] }]

const messages = await client.getPrompt('summarize', { topic: 'quarterly results' })
// => [{ role: 'user', content: { type: 'text', text: 'Summarize quarterly results' } }]

MCPResourceHandler

Server-side definition of a resource exposed via the resources option of MCPServerConfig.

interface MCPResourceHandler {
  uri: string           // Unique resource identifier
  name: string          // Human-readable name
  description?: string  // Resource description
  mimeType?: string     // MIME type of the content
  read: () => Promise<string | { text?: string; blob?: string }>
}

read() may return a plain string (treated as text) or an object with text and/or base64 blob content.

MCPPromptHandler

Server-side definition of a prompt template exposed via the prompts option of MCPServerConfig.

interface MCPPromptHandler {
  name: string                       // Unique prompt name
  description?: string               // Prompt description
  arguments?: MCPPromptArgument[]    // Declared template arguments
  get: (args?: Record<string, string>) => Promise<MCPPromptMessage[]>
}

Exposing Resources & Prompts

When resources or prompts are provided to createMCPServer, the server advertises the corresponding capabilities during initialize and serves resources/list, resources/read, prompts/list, and prompts/get requests.

const server = createMCPServer({
  name: 'docs-server',
  tools: [],
  resources: [
    {
      uri: 'file:///docs/readme.md',
      name: 'README',
      mimeType: 'text/markdown',
      read: async () => '# Project docs\n...',
    },
  ],
  prompts: [
    {
      name: 'summarize',
      description: 'Summarize a topic',
      arguments: [{ name: 'topic', required: true }],
      get: async (args) => [
        {
          role: 'user',
          content: { type: 'text', text: `Summarize ${args?.topic}` },
        },
      ],
    },
  ],
})

await server.start()

HTTP Handler

createMCPHttpHandler returns a function that maps a standard Request to a Response, so it can be mounted in any runtime that speaks the web Fetch API (edge functions, Bun, Deno, Node with an adapter, etc.). It exposes the same tools, resources, and prompts as the stdio server but does not manage a process lifecycle.

MCPHttpHandlerConfig

interface MCPHttpHandlerConfig {
  name: string                       // Server name
  version?: string                   // Server version
  tools: Tool[]                      // ElsiumAI tools to expose via MCP
  resources?: MCPResourceHandler[]   // Resources to expose via MCP
  prompts?: MCPPromptHandler[]       // Prompt templates to expose via MCP
}

MCPHttpHandler

type MCPHttpHandler = (request: Request) => Promise<Response>

Only POST requests are accepted (others return 405). The request body is parsed as a single JSON-RPC message; malformed JSON returns a -32700 parse error. Notifications (e.g. notifications/initialized) produce a 204 No Content response.

Example

import { createMCPHttpHandler, createMCPClient } from '@elsium-ai/mcp'

const handler = createMCPHttpHandler({
  name: 'math-tools',
  version: '1.0.0',
  tools: [calculator],
})

// Mount in any Fetch-API runtime
export default { fetch: handler }

// ...or pair with an MCP HTTP client
const client = createMCPClient({
  name: 'math-tools',
  transport: 'http',
  url: 'http://localhost:3000/mcp',
})
await client.connect()

Resource & Prompt Types

Shared metadata and content types returned by the client resource and prompt methods.

interface MCPResource {
  uri: string
  name: string
  description?: string
  mimeType?: string
}

interface MCPResourceContent {
  uri: string
  mimeType?: string
  text?: string
  blob?: string   // base64-encoded binary content
}

interface MCPPrompt {
  name: string
  description?: string
  arguments?: MCPPromptArgument[]
}

interface MCPPromptArgument {
  name: string
  description?: string
  required?: boolean
}

interface MCPPromptMessage {
  role: 'user' | 'assistant'
  content: { type: 'text'; text: string }
}

Capability Guard

Gates callTool on a CapabilityToken, so an MCP client can only invoke tools the token is authorized to use. Every other method (connect, listTools, readResource, etc.) is passed through unchanged.

createCapabilityGuardedMCPClient

createCapabilityGuardedMCPClient(
  client: MCPClient,
  options: CapabilityGuardedMCPOptions,
): MCPClient

Wraps an existing MCPClient. On each callTool, it optionally verifies the token via options.verifier, then checks the token’s scope against { server, tool } with canUseMcp. A denied call throws an ElsiumError with code AUTH_ERROR and (if provided) invokes options.onDeny.

CapabilityGuardedMCPOptions

MCPCapabilityDenialEvent

import { createMCPClient, createCapabilityGuardedMCPClient } from '@elsium-ai/mcp'

const guarded = createCapabilityGuardedMCPClient(
  createMCPClient({ name: 'data-tools', transport: 'http', url: 'http://localhost:3001/mcp' }),
  {
    token,
    server: 'data-tools',
    onDeny: (event) => console.warn('MCP call denied', event),
  },
)

await guarded.connect()
await guarded.callTool('query_db', { sql: 'SELECT 1' }) // throws AUTH_ERROR if not authorized

Types

Part of ElsiumAI

This package is the MCP (Model Context Protocol) layer of the ElsiumAI framework. See the Getting Started guide or the Fundamentals for comprehensive coverage of every feature.

License

MIT