@ellie-ai/agent-mcp-plugin

MCP (Model Context Protocol) plugin for Ellie agents. Connects to MCP servers and dynamically registers their tools with your agent.

Overview

The MCP plugin allows your agents to access tools from any MCP server:

• Local servers via stdio (npx, docker, etc.)
• Remote servers via HTTP with authentication
• Multiple servers simultaneously
• Dynamic tool discovery - tools are registered automatically

Installation

bun install @ellie-ai/agent-mcp-plugin

Quick Start

import { createRuntime } from "@ellie-ai/runtime";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import { mcpPlugin } from "@ellie-ai/agent-mcp-plugin";
import { openAI } from "@ellie-ai/model-providers";

const runtime = createRuntime({
  plugins: [
    agentPlugin({
      model: openAI({ model: "gpt-4o" }),
      toolPlugins: [
        mcpPlugin({
          servers: [
            {
              type: "stdio",
              name: "filesystem",
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
            },
          ],
        }),
      ],
    }),
  ],
});

await runtime.execute("List files in /tmp").completed;

HTTP Server Example

Connect to remote MCP servers with authentication:

import { mcpPlugin } from "@ellie-ai/agent-mcp-plugin";
import { agentPlugin } from "@ellie-ai/agent-plugin";
import { openAI } from "@ellie-ai/model-providers";

const runtime = createRuntime({
  plugins: [
    agentPlugin({
      model: openAI(),
      toolPlugins: [
        mcpPlugin({
          servers: [
            {
              type: "http",
              name: "nexus",
              url: "https://nexus.civic.com/hub/mcp",
              headers: {
                Authorization: `Bearer ${accessToken}`,
              },
            },
          ],
        }),
      ],
    }),
  ],
});

Multiple Servers

Connect to multiple MCP servers at once:

agentPlugin({
  model: openAI(),
  toolPlugins: [
    mcpPlugin({
      servers: [
        {
          type: "stdio",
          name: "filesystem",
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "."],
        },
        {
          type: "stdio",
          name: "github",
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-github"],
          env: {
            GITHUB_TOKEN: process.env.GITHUB_TOKEN,
          },
        },
        {
          type: "http",
          name: "remote-api",
          url: "https://api.example.com/mcp",
          headers: {
            "X-API-Key": process.env.API_KEY,
          },
        },
      ],
    }),
  ],
})

All tools from all servers are available to your agent.

Configuration

Server Types

Stdio Server

{
  type: "stdio",
  name: string,           // Unique name for this server
  command: string,        // Command to run (e.g., "npx", "docker")
  args?: string[],        // Optional arguments
  env?: Record<string, string>  // Optional environment variables
}

HTTP Server

{
  type: "http",
  name: string,           // Unique name for this server
  url: string,            // Server URL
  headers?: Record<string, string>  // Optional headers (auth, etc.)
}

Plugin Options

{
  servers: MCPServerConfig[],  // Required: List of servers to connect to
  autoConnect?: boolean,        // Optional: Auto-connect on init (default: true)
  retry?: {                     // Optional: Retry configuration
    maxAttempts: number,
    delayMs: number
  }
}

How It Works

1. Connection: Plugin connects to all configured MCP servers
2. Discovery: For each server, calls listTools() to discover available tools
3. Registration: Dynamically registers tools with the agent using registerAgentTool()
4. Execution: When model calls a tool, the plugin routes it to the appropriate MCP server
5. Response: Tool result is returned to the model

State

The plugin maintains state about connected servers:

{
  mcp: {
    servers: {
      [name: string]: {
        name: string,
        config: MCPServerConfig,
        client: Client,
        tools: Tool[],
        connected: boolean,
        error?: string
      }
    },
    tools: Tool[],  // All tools across all servers
    status: "initializing" | "connected" | "error",
    error?: string
  }
}

You can inspect this state:

const state = runtime.getState();
console.log(state.mcp.servers);  // Connected servers
console.log(state.mcp.tools);    // All available tools

Actions

The plugin dispatches these actions:

{ type: "MCP_SERVER_CONNECTING", serverName: string }
{ type: "MCP_SERVER_CONNECTED", serverName: string, tools: Tool[] }
{ type: "MCP_SERVER_ERROR", serverName: string, error: string }
{ type: "MCP_TOOLS_REGISTERED", tools: Tool[] }

You can listen for these in middleware:

import { whenAction } from "@ellie-ai/runtime";

const logMCP = whenAction(
  (action) => action.type.startsWith("MCP_"),
  ({ action }) => {
    console.log("MCP action:", action);
  }
);

Common MCP Servers

Filesystem

{
  type: "stdio",
  name: "filesystem",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
}

GitHub

{
  type: "stdio",
  name: "github",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: {
    GITHUB_TOKEN: process.env.GITHUB_TOKEN
  }
}

Brave Search

{
  type: "stdio",
  name: "brave-search",
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-brave-search"],
  env: {
    BRAVE_API_KEY: process.env.BRAVE_API_KEY
  }
}

Docker

{
  type: "stdio",
  name: "docker",
  command: "docker",
  args: ["run", "-i", "--rm", "mcp-server-image"]
}

Error Handling

Connection errors are logged and dispatched as actions:

runtime.execute("...").completed.catch((error) => {
  const mcpState = runtime.getState().mcp;

  // Check for server errors
  Object.values(mcpState.servers).forEach((server) => {
    if (server.error) {
      console.error(`Server ${server.name} error:`, server.error);
    }
  });
});

Security

Stdio servers:

• Run in separate processes
• Can access local filesystem
• Use environment variables for secrets

HTTP servers:

• Use HTTPS in production
• Pass auth tokens via headers
• Validate server certificates

Best practices:

• Don't hardcode credentials
• Use environment variables
• Validate tool inputs
• Sanitize tool outputs

Debugging

Enable MCP debug logging:

import { whenAction } from "@ellie-ai/runtime";

const debugMCP = {
  middleware: whenAction(
    (action) => action.type.startsWith("MCP_"),
    ({ action }) => {
      console.log("[MCP]", action.type, action);
    }
  )
};

createRuntime({
  plugins: [mcpPlugin({ ... }), debugMCP, agentPlugin({ ... })],
});

Examples

See examples/mcp-integration.ts for complete working examples.

Learn More

• Model Context Protocol - Official MCP documentation
• MCP Servers - Official MCP server implementations
• @ellie-ai/agent-plugin - Agent plugin documentation
• Plugin Development Guide - Building plugins guide