Model Context Protocol (MCP)

PicoClaw supports the Model Context Protocol (MCP), allowing you to extend the agent with external tools and services. MCP provides a standardized way to connect AI assistants with external data sources and tools.

Overview

MCP enables PicoClaw to:

Connect to external MCP servers
Use tools provided by MCP servers
Access external data sources and APIs
Integrate with third-party services

How MCP Works

PicoClaw Agent
    ↓
    ↓ (calls mcp_tool)
    ↓
MCP Manager
    ↓
    ↓ (forwards request)
    ↓
MCP Server (external)
    ↓
    ↓ (executes tool)
    ↓
External Service/API

Configuration

Add MCP server configuration to ~/.picoclaw/config.json:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
        "enabled": true
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "ghp_your_token_here"
        },
        "enabled": true
      },
      "postgres": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
        "enabled": false
      }
    }
  }
}

Server Configuration

Field	Type	Required	Description
`command`	string	Yes	Command to execute MCP server
`args`	array	No	Arguments for the command
`env`	object	No	Environment variables for the server
`enabled`	boolean	No	Enable/disable the server (default: true)

Available MCP Servers

MCP has a growing ecosystem of official and community servers:

Official Servers

Filesystem

Read and manipulate local files.

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "enabled": true
  }
}

GitHub

Interact with GitHub repositories, issues, and PRs.

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "ghp_..."
    },
    "enabled": true
  }
}

PostgreSQL

Query and manage PostgreSQL databases.

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/db"],
    "enabled": true
  }
}

Google Drive

Access Google Drive files.

{
  "gdrive": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-gdrive"],
    "env": {
      "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json"
    },
    "enabled": true
  }
}

Slack

Interact with Slack workspaces.

{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-..."
    },
    "enabled": true
  }
}

Finding More Servers

Browse available MCP servers:

Using MCP Tools

Once MCP servers are configured, their tools are automatically available to the agent.

Tool Discovery

The agent sees MCP tools with the mcp_ prefix:

Available tools:
- mcp_filesystem_read_file
- mcp_filesystem_write_file  
- mcp_github_create_issue
- mcp_github_list_repos
- mcp_postgres_query

Tool Naming Convention

MCP tools are named:

mcp_{server}_{tool}

Examples:

mcp_github_create_issue - GitHub server’s “create_issue” tool
mcp_filesystem_read_file - Filesystem server’s “read_file” tool
mcp_postgres_query - Postgres server’s “query” tool

Name Sanitization

Tool names are sanitized for compatibility:

Converted to lowercase
Special characters replaced with underscores
Limited to 64 characters (OpenAI API limit)
Hash appended if sanitization is lossy

Examples:

My-Tool! → my_tool
Very Long Tool Name With Spaces → very_long_tool_name_with_spaces
Tool@#$%Name → tool_name_12ab34cd (hash appended)

Automatic Usage

The agent uses MCP tools automatically: Example 1: GitHub Integration

User: "Create a GitHub issue for the bug we just found"

Agent: [calls mcp_github_create_issue with appropriate parameters]

Result: "Created issue #123: Fix web search timeout"

Example 2: Database Query

User: "How many users signed up today?"

Agent: [calls mcp_postgres_query with SQL]

Result: "42 users signed up today"

Implementation Details

MCPTool Wrapper

Each MCP tool is wrapped to implement PicoClaw’s Tool interface:

type MCPTool struct {
    manager    MCPManager
    serverName string
    tool       *mcp.Tool
}

func (t *MCPTool) Name() string
func (t *MCPTool) Description() string  
func (t *MCPTool) Parameters() map[string]any
func (t *MCPTool) Execute(ctx context.Context, args map[string]any) *ToolResult

Tool Execution Flow

Agent calls MCP tool via name (e.g., mcp_github_create_issue)
MCPTool wrapper forwards to MCP Manager
MCP Manager communicates with external server
Server executes tool and returns result
Result wrapped in ToolResult and returned to agent

Error Handling

MCP tool errors are properly handled:

if result.IsError {
    return ErrorResult(fmt.Sprintf("MCP tool returned error: %s", errMsg))
}

Errors include:

Connection failures
Server not responding
Tool execution errors
Invalid parameters

Content Types

MCP tools can return different content types:

Text: Plain text responses
Images: Image data with MIME type
Other: Custom content types

Example handling:

switch v := content.(type) {
case *mcp.TextContent:
    return v.Text
case *mcp.ImageContent:
    return fmt.Sprintf("[Image: %s]", v.MIMEType)
default:
    return fmt.Sprintf("[Content: %T]", v)
}

Security Considerations

Server Trust

Only configure MCP servers from trusted sources:

Official MCP servers from Model Context Protocol
Well-maintained community servers
Servers you’ve audited yourself

Credential Management

Never commit credentials to config files: ❌ Bad:

{
  "github": {
    "env": {
      "GITHUB_TOKEN": "ghp_actual_token_here"
    }
  }
}

✅ Good:

{
  "github": {
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

Then set environment variable:

export GITHUB_TOKEN=ghp_your_token
picoclaw gateway

Workspace Restrictions

MCP tools respect PicoClaw’s workspace restrictions:

If restrict_to_workspace: true, tools are sandboxed
External servers may have their own access controls
Review server permissions before enabling

Creating Custom MCP Servers

You can create custom MCP servers for your specific needs.

Example: Custom Weather Server

#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

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

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "get_weather") {
    const location = request.params.arguments.location;
    // Fetch weather data...
    return {
      content: [
        {
          type: "text",
          text: `Weather in ${location}: Sunny, 72°F`
        }
      ]
    };
  }
  throw new Error("Unknown tool");
});

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

Register Custom Server

{
  "mcp": {
    "servers": {
      "weather": {
        "command": "node",
        "args": ["/path/to/weather-server.js"],
        "enabled": true
      }
    }
  }
}

Troubleshooting

Server Not Starting

Check command is available:

which npx
node --version

Test server manually:

npx -y @modelcontextprotocol/server-github

Check logs:

picoclaw gateway 2>&1 | grep mcp

Tools Not Appearing

Verify server is enabled:

{
  "enabled": true
}

Check server configuration:
- Command path correct
- Arguments properly formatted
- Environment variables set
Restart gateway:

picoclaw gateway

Authentication Errors

Verify credentials:
- API tokens are valid
- Environment variables are set
- Credentials have necessary permissions
Check token format:
- GitHub: ghp_...
- Slack: xoxb-...

Tool Execution Fails

Check tool parameters:
- Review required parameters
- Verify parameter types
- Check parameter constraints
Test tool independently:
- Use MCP inspector/debugger
- Call tool directly from server

MCP Resources

Documentation

Tools & Utilities

Skills System - Custom instruction sets
Web Search - Built-in web search providers
Tools Reference - All available tools

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Overview

​How MCP Works

​Configuration

​Server Configuration

​Available MCP Servers

​Official Servers

​Filesystem

​GitHub

​PostgreSQL

​Google Drive

​Slack

​Finding More Servers

​Using MCP Tools

​Tool Discovery

​Tool Naming Convention

​Name Sanitization

​Automatic Usage

​Implementation Details

​MCPTool Wrapper

​Tool Execution Flow

​Error Handling

​Content Types

​Security Considerations

​Server Trust

​Credential Management

​Workspace Restrictions

​Creating Custom MCP Servers

​Example: Custom Weather Server

​Register Custom Server

​Troubleshooting

​Server Not Starting

​Tools Not Appearing

​Authentication Errors

​Tool Execution Fails

​MCP Resources

​Documentation

​Tools & Utilities

​Related Features

Build docs developers (and LLMs) love

Overview

How MCP Works

Configuration

Server Configuration

Available MCP Servers

Official Servers

Filesystem

GitHub

PostgreSQL

Google Drive

Slack

Finding More Servers

Using MCP Tools

Tool Discovery

Tool Naming Convention

Name Sanitization

Automatic Usage

Implementation Details

MCPTool Wrapper

Tool Execution Flow

Error Handling

Content Types

Security Considerations

Server Trust

Credential Management

Workspace Restrictions

Creating Custom MCP Servers

Example: Custom Weather Server

Register Custom Server

Troubleshooting

Server Not Starting

Tools Not Appearing

Authentication Errors

Tool Execution Fails

MCP Resources

Documentation

Tools & Utilities

Related Features