MCP Integration

Connect external tools and services via the Model Context Protocol.

What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI models to external tools and data sources. Moxxy supports MCP servers, making their tools available as agent skills.

Architecture

┌─────────────────────────────────────────────────────┐
│                    Moxxy Agent                       │
├─────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────┐   │
│  │              MCP Client                      │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐    │   │
│  │  │ Server A │ │ Server B │ │ Server C │    │   │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘    │   │
│  └───────┼────────────┼────────────┼──────────┘   │
└──────────┼────────────┼────────────┼──────────────┘
           │            │            │
           ▼            ▼            ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │Filesystem│ │ Database │ │   API    │
    │   MCP    │ │   MCP    │ │   MCP    │
    └──────────┘ └──────────┘ └──────────┘

Adding MCP Servers

Via Web Dashboard

1. Open web dashboard
2. Go to Config → MCP Servers
3. Click Add Server
4. Configure:
   • Name: Identifier for the server
   • Command: Executable path or command
   • Args: Command-line arguments
   • Env: Environment variables

Via Configuration

MCP servers are stored in the agent's memory:

# Add an MCP server
moxxy run --agent default --prompt "Add MCP server 'filesystem' with command 'mcp-filesystem' and args ['/home/user']"

Configuration Example

{
  "name": "filesystem",
  "command": "mcp-filesystem",
  "args": ["/home/user/projects"],
  "env": {}
}

Available MCP Servers

Official MCP Servers

Server	Description	Installation
@modelcontextprotocol/server-filesystem	Filesystem access	npm install -g @modelcontextprotocol/server-filesystem
@modelcontextprotocol/server-postgres	PostgreSQL database	npm install -g @modelcontextprotocol/server-postgres
@modelcontextprotocol/server-sqlite	SQLite database	npm install -g @modelcontextprotocol/server-sqlite
@modelcontextprotocol/server-github	GitHub API	npm install -g @modelcontextprotocol/server-github
@modelcontextprotocol/server-git	Git operations	npm install -g @modelcontextprotocol/server-git
@modelcontextprotocol/server-puppeteer	Browser automation	npm install -g @modelcontextprotocol/server-puppeteer

Community Servers

Many community MCP servers are available for:

• Slack
• Linear
• Jira
• Google Drive
• AWS
• And more...

Using MCP Tools

Once an MCP server is configured, its tools are available as agent skills with [MCP] prefix.

Invocation Format

<invoke name="mcp">["server_name", "tool_name", {"param": "value"}]</invoke>

Examples

Filesystem MCP

<invoke name="mcp">["filesystem", "read_file", {"path": "/home/user/data.txt"}]</invoke>
<invoke name="mcp">["filesystem", "write_file", {"path": "/home/user/output.txt", "content": "Hello!"}]</invoke>
<invoke name="mcp">["filesystem", "list_directory", {"path": "/home/user"}]</invoke>

PostgreSQL MCP

<invoke name="mcp">["postgres", "query", {"sql": "SELECT * FROM users LIMIT 10"}]</invoke>

GitHub MCP

<invoke name="mcp">["github", "search_repositories", {"query": "moxxy ai"}]</invoke>
<invoke name="mcp">["github", "get_issue", {"owner": "moxxy-ai", "repo": "moxxy", "issue_number": 1}]</invoke>

Agent Integration

MCP tools appear in the agent's skill catalog:

--- AVAILABLE SKILLS ---

[MCP] filesystem:read_file (from filesystem server)
  Read file contents
  Usage: <invoke name="mcp">["filesystem", "read_file", {"path": "..."}]</invoke>

[MCP] filesystem:write_file (from filesystem server)
  Write content to file
  Usage: <invoke name="mcp">["filesystem", "write_file", {"path": "...", "content": "..."}]</invoke>

...
--- END OF SKILLS ---

Automatic Discovery

When an MCP server is added:

1. Moxxy connects to the server
2. Discovers available tools
3. Registers each tool as a skill
4. Agent can immediately use them

Configuration Reference

Server Configuration

{
  "name": "my_server",
  "command": "/path/to/mcp-server",
  "args": ["--option", "value"],
  "env": {
    "API_KEY": "secret",
    "DEBUG": "true"
  }
}

Field	Type	Description
name	string	Unique identifier
command	string	Executable path
args	array	Command-line arguments
env	object	Environment variables

Environment Variables

Use vault for sensitive values:

# Store API key in vault
moxxy run --agent default --prompt "Store 'secret_key' in vault as GITHUB_TOKEN"

Then reference in MCP config:

{
  "env": {
    "GITHUB_TOKEN": "{{vault.GITHUB_TOKEN}}"
  }
}

Security Considerations

Permissions

MCP tools run with the same permissions as the Moxxy process. Consider:

1. What data can they access?
2. What actions can they perform?
3. Are credentials properly secured?

Best Practices

1. Use minimal permissions - Only grant necessary access
2. Audit MCP servers - Review tools they provide
3. Secure credentials - Use vault for secrets
4. Monitor usage - Check logs for MCP calls
5. Update regularly - Keep servers updated

Troubleshooting

MCP Server Won't Start

1. Check command path:

   which mcp-filesystem

2. Verify arguments:

   mcp-filesystem /home/user --help

3. Check logs:

   moxxy logs | grep -i mcp

Tool Not Found

1. Verify server is connected
2. Check tool name spelling
3. List available tools via API:

   curl http://localhost:17890/api/agents/default/mcp/tools

Authentication Failed

1. Verify credentials in vault
2. Check environment variable references
3. Test MCP server directly

Creating Custom MCP Servers

You can create your own MCP servers in any language:

Node.js Example

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

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

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'hello',
    description: 'Say hello',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      }
    }
  }]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'hello') {
    return {
      content: [{
        type: 'text',
        text: `Hello, ${request.params.arguments.name}!`
      }]
    };
  }
});

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

See MCP Documentation for full guide.

API Reference

List MCP Servers

curl http://localhost:17890/api/agents/default/mcp/servers

List MCP Tools

curl http://localhost:17890/api/agents/default/mcp/tools

Add MCP Server

curl -X POST http://localhost:17890/api/agents/default/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "command": "mcp-filesystem",
    "args": ["/home/user"],
    "env": {}
  }'

Remove MCP Server

curl -X DELETE http://localhost:17890/api/agents/default/mcp/servers/filesystem

Invoke MCP Tool

curl -X POST http://localhost:17890/api/agents/default/mcp/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "server": "filesystem",
    "tool": "read_file",
    "arguments": {"path": "/home/user/data.txt"}
  }'