AI Platform

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.

4 min readUpdated DocumentationEdit this page
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.

TypeScript
TS
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

OptionDefaultDescription
serverUrlrequiredHTTP 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
timeoutMs30000Request timeout in milliseconds

Discover MCP Tools

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

TypeScript
TS
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.

TypeScript
TS
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 error

The first argument is the MCP tool name, and the second contains the arguments passed to the tool.

Resources and Prompts

TypeScript
TS
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().

TypeScript
TS
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:

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

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:

  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.
TypeScript
TS
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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY