Custom MCP Servers

Connect any MCP-compatible server to Agent Nine. This lets you integrate custom tools, databases, APIs, or internal services.

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI assistants to external tools and data sources. Any service that implements the MCP protocol can be connected to Agent Nine.

Setting Up a Custom MCP Server

1. Create a config file

Create .agent-nine/mcp.json in your project directory:

{
  "servers": [
    {
      "name": "my-database",
      "command": "npx",
      "args": ["@my-org/mcp-postgres", "--connection-string", "postgresql://localhost/mydb"],
      "description": "Query the project database"
    }
  ]
}

2. Restart Agent Nine

The desktop app will detect the config and connect to the MCP server automatically.

3. Use it

Once connected, Agent Nine can use the tools provided by your MCP server:

Query the database for all users created this week

Config Format

Each server entry supports:

Field	Required	Description
name	Yes	Unique name for the server
command	Yes	Command to start the server
args	No	Arguments for the command
env	No	Environment variables
description	No	Description shown in the UI

Example: Multiple servers

{
  "servers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost/app"],
      "description": "App database"
    },
    {
      "name": "redis",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-redis"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      },
      "description": "Redis cache"
    },
    {
      "name": "internal-api",
      "command": "node",
      "args": ["./tools/mcp-server.js"],
      "description": "Internal company API"
    }
  ]
}

Available Community Servers

Popular MCP servers you can use:

Server	Package	Description
PostgreSQL	@modelcontextprotocol/server-postgres	Query PostgreSQL databases
SQLite	@modelcontextprotocol/server-sqlite	Read/write SQLite databases
Filesystem	@modelcontextprotocol/server-filesystem	Sandboxed file access
Brave Search	@modelcontextprotocol/server-brave-search	Web search via Brave
Puppeteer	@modelcontextprotocol/server-puppeteer	Browser automation
Memory	@modelcontextprotocol/server-memory	Persistent key-value store
Slack	@modelcontextprotocol/server-slack	Slack workspace access
Google Maps	@modelcontextprotocol/server-google-maps	Places, directions, geocoding

Find more at modelcontextprotocol.io.

Building Your Own MCP Server

If you need a custom integration, you can build your own MCP server:

1. Use the MCP SDK (@modelcontextprotocol/sdk)
2. Define your tools (functions the AI can call)
3. Run as a stdio process
4. Add to .agent-nine/mcp.json

Minimal example

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "get_weather",
    description: "Get current weather for a city",
    inputSchema: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" }
      },
      required: ["city"]
    }
  }]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const city = request.params.arguments.city;
    return { content: [{ type: "text", text: `Weather in ${city}: Sunny, 22°C` }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Troubleshooting

Server doesn't appear

• Make sure .agent-nine/mcp.json is in your project root
• Restart the desktop app after adding the config
• Check that the command is installed and runnable

Server crashes

• Check the server logs in the desktop app (Settings → MCP)
• Make sure all required environment variables are set
• Try running the command manually to see errors

Tools not working

• Agent Nine discovers tools automatically from the MCP server
• If a tool isn't showing up, the server might not be returning it in tools/list