Model Context Protocol (MCP)

AxilJS provides an MCPClient for connecting AI applications to Model Context Protocol (MCP) servers.

With the MCP client, you can connect to an MCP server, discover available tools, execute MCP tools, and expose those tools to AxilJS AI agents.

This allows AI agents to interact with capabilities provided by external MCP servers.

Connect to an MCP Server#

Import MCPClient from @axiljs/ai and create a client with the MCP server URL.

import { MCPClient } from '@axiljs/ai'
 
const client = new MCPClient({
  serverUrl: 'http://localhost:8080'
})
 
await client.connect()

After calling connect(), the client establishes a connection with the configured MCP server.

The serverUrl should point to the HTTP endpoint exposed by your MCP server.

Discover MCP Tools#

Use listTools() to retrieve the tools exposed by the connected MCP server.

const tools = await client.listTools()

This allows your application to discover the capabilities available through the MCP server without hard-coding every tool.

Call an MCP Tool#

Use callTool() to execute a specific tool exposed by the MCP server.

const result = await client.callTool(
  'read_file',
  {
    path: '/etc/hosts'
  }
)

The first argument is the MCP tool name, while the second argument contains the input passed to the tool.

This provides a programmatic way for an AxilJS application to invoke capabilities exposed by an MCP server.

Use MCP Tools with AI Agents#

MCP tools can be converted into agent-compatible tools with asAgentTools().

const mcpTools = await client.asAgentTools()
 
const agent = new Agent({
  provider: ai,
  tools: [
    ...builtIn,
    ...mcpTools
  ]
})

This allows an AxilJS Agent to use tools provided by an MCP server alongside built-in or application-defined tools.

A typical integration flow is:

MCP Server
    │
    ▼
MCPClient
    │
    ├── listTools()
    │
    ├── callTool()
    │
    └── asAgentTools()
            │
            ▼
        AxilJS Agent
            │
            ▼
       AI Application

This architecture is useful when you want to extend an AI agent with capabilities maintained outside the main application.

MCP Protocol#

MCP uses JSON-RPC 2.0 over HTTP in the AxilJS integration shown above.

Protocol: Model Context Protocol (MCP)
Transport: HTTP
RPC: JSON-RPC 2.0
Protocol version: 2024-11-05

Common MCP Use Cases#

An MCP client can be useful when an AI application needs access to tools or capabilities provided by external MCP servers.

Typical use cases include:

• Connecting AI agents to MCP servers
• Discovering external tools dynamically
• Calling MCP tools from TypeScript applications
• Extending AxilJS agents with MCP capabilities
• Integrating external services into AI workflows
• Building tool-enabled AI assistants

MCP Client Workflow#

A basic AxilJS MCP integration follows this sequence:

1. Create an MCPClient with the MCP server URL.
2. Connect to the MCP server with connect().
3. Discover available tools with listTools().
4. Call individual tools with callTool(), or convert the tools with asAgentTools().
5. Pass MCP tools to an AxilJS Agent when agent-based execution is required.

import { Agent, MCPClient } from '@axiljs/ai'
 
const client = new MCPClient({
  serverUrl: 'http://localhost:8080'
})
 
await client.connect()
 
const mcpTools = await client.asAgentTools()
 
const agent = new Agent({
  provider: ai,
  tools: mcpTools
})

This provides a direct path from an MCP server to an AxilJS AI agent.