Model Context Protocol (MCP)
Connect AxilJS apps to Model Context Protocol (MCP) servers over HTTP: discover and call tools, read resources and prompts, and give MCP tools to AI agents.
On this page9
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 and execute its tools, read its resources and prompt templates, and expose its tools to AxilJS AI agents.
Connect to an MCP Server
Import MCPClient from @axiljs/ai and create a client with the MCP server URL.
1import { MCPClient } from '@axiljs/ai'
2
3const client = new MCPClient({
4 serverUrl: 'http://localhost:8080/mcp'
5})
6
7await client.connect()connect() performs the MCP initialize handshake and sends the notifications/initialized notification. Every other method throws if it is called before connect().
Client Options
| Option | Default | Description |
|---|---|---|
serverUrl | required | HTTP endpoint of the MCP server, used exactly as given (path, trailing slash, and query string are kept) |
clientName | 'AxilJS-MCP-Client' | Client name sent to the server during initialization |
clientVersion | '0.1.0' | Client version sent to the server |
timeoutMs | 30000 | Request timeout in milliseconds |
Discover MCP Tools
Use listTools() to retrieve the tools exposed by the connected MCP server.
const tools = await client.listTools()
// [{ name, description, inputSchema }]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.
1const result = await client.callTool('read_file', {
2 path: './README.md'
3})
4
5result.content // [{ type: 'text', text: '...' }, ...]
6result.isError // true if the tool reported an errorThe first argument is the MCP tool name, and the second contains the arguments passed to the tool.
Resources and Prompts
1const resources = await client.listResources() // [{ uri, name, description?, mimeType? }]
2const file = await client.readResource('file:///notes.txt') // { uri, mimeType?, text?, blob? }
3
4const prompts = await client.listPrompts() // [{ name, description?, arguments? }]
5const prompt = await client.getPrompt('summarize', { topic: 'release notes' })
6prompt.messages // filled-in prompt messages
7
8await client.disconnect()Use MCP Tools with AI Agents
MCP tools can be converted into agent-compatible tools with asAgentTools().
1import { Agent, calculatorTool } from '@axiljs/ai'
2
3const mcpTools = await client.asAgentTools()
4
5const agent = new Agent({
6 provider: ai,
7 tools: [
8 calculatorTool,
9 ...mcpTools
10 ]
11})Each converted tool calls the MCP server through callTool() and returns the tool's text content (joined with newlines). If the MCP server marks the result as an error, the tool throws, and the agent reports the error to the model.
A typical integration flow is:
This architecture is useful when you want to extend an AI agent with capabilities maintained outside the main application.
MCP Protocol
The client speaks JSON-RPC 2.0 over HTTP POST and requests MCP protocol version 2024-11-05.
It accepts both plain JSON responses and Streamable HTTP responses (text/event-stream). For a streamed response, the request resolves as soon as the matching JSON-RPC message arrives, even if the server keeps the stream open. A session ID returned by the server in the Mcp-Session-Id header is sent back on later requests.
Note
The MCP client prints connect and disconnect messages to the console. It does not take a logger option.
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:
- Create an
MCPClientwith the MCP server URL. - Connect to the MCP server with
connect(). - Discover available tools with
listTools(). - Call individual tools with
callTool(), or convert the tools withasAgentTools(). - Pass MCP tools to an AxilJS
Agentwhen agent-based execution is required.
1import { Agent, MCPClient } from '@axiljs/ai'
2
3const client = new MCPClient({
4 serverUrl: 'http://localhost:8080/mcp'
5})
6
7await client.connect()
8
9const mcpTools = await client.asAgentTools()
10
11const agent = new Agent({
12 provider: ai,
13 tools: mcpTools
14})This provides a direct path from an MCP server to an AxilJS AI agent.
Was this page helpful?