IDE
CLI

MCP Usage Documentation ​

Overview ​

MCP (Model Context Protocol) is an open standard that allows CodeBuddy to integrate with external tools and data sources. With MCP, you can extend the functionality of CodeBuddy by connecting it to various external services, databases, APIs, and more.

Core Concepts ​

MCP Server ​

An MCP server is an independent process that provides tools and resources, and CodeBuddy communicates with these servers via different transport protocols.

Transport Types ​

  • STDIO: Communication with local processes via standard input/output

  • SSE: Communication with remote services via Server-Sent Events

  • HTTP: Communication with remote services via HTTP streaming

Configuration Scope ​

  • user: Global user configuration, applied to all projects

  • project: Project-level configuration, applied to specific projects

  • local: Local configuration, applied only to the current session or workspace

For services with the same name (i.e., configurations with the same name in multiple scopes), the priority is as follows: local > project > user

Security Approval Mechanism ​

MCP servers in the project scope require user approval upon first connection to ensure security. The system will display the server details, and the user can choose to approve or deny the connection.

Configuration Files ​

Configuration File Locations ​

  • user scope: ~/.codebuddy.json

  • project scope: <project root directory>/.mcp.json

  • local scope: ~/.codebuddy.json#/projects/<workspace_path>

Configuration File Format ​

json
{
  "mcpServers": {
    "server-name": {
      "type": "stdio|sse|http",
      "command": "command path",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "url": "http://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      },
      "description": "Server description"
    }
  },
  "//": "The projects field is only valid in the user scope file and identifies local scope configurations",
  "projects": {
    "/path/to/project": {
      "mcpServers": {
        "local-server": {
          "type": "stdio",
          "command": "./local-tool"
        }
      }
    }
  }
}

Command Line Usage ​

Add MCP Server ​

STDIO Server ​

bash
# Add a local executable
codebuddy mcp add --scope user my-tool -- /path/to/tool arg1 arg2

# Add a Python script
codebuddy mcp add --scope project python-tool -- python /path/to/script.py

SSE Server ​

bash
# Add an SSE server
codebuddy mcp add --scope user --transport sse sse-server https://example.com/mcp/sse

HTTP Server ​

bash
# Add an HTTP streaming server
codebuddy mcp add --scope project --transport http http-server https://example.com/mcp/http

Add Server Using JSON Configuration ​

bash
# Add via JSON string
codebuddy mcp add-json --scope user my-server '{"type":"stdio","command":"/usr/local/bin/tool","args":["--verbose"]}'

Manage MCP Servers ​

List All Servers ​

bash
# List servers for all scopes
codebuddy mcp list

View Server Details ​

bash
# View specific server information
codebuddy mcp get my-server

Remove Server ​

bash
# Remove a specific server
codebuddy mcp remove my-server

# Remove a server from a specific scope
codebuddy mcp remove my-server --scope user

Best Practices ​

1. Scope Selection ​

  • Use user scope to store personal tools and global services

  • Use project scope to store project-specific tools

  • Use local scope to store temporary or experimental tools

2. Security Considerations ​

  • Avoid storing sensitive information in configuration files

  • Use environment variables to pass authentication information

  • Regularly review and update server configurations

  • MCP servers in the project scope require user approval to connect, ensuring security

3. Performance Optimization ​

  • Properly configure server timeouts

  • Avoid running too many STDIO servers simultaneously

  • Use caching mechanisms to reduce redundant connections

4. Error Handling ​

  • Monitor server connection status

  • Implement reconnection mechanisms

  • Log and analyze error logs

Troubleshooting ​

Common Issues ​

Server Connection Failure ​

  1. Check if the command path is correct

  2. Verify the parameters and environment variables

  3. Confirm network connectivity (for remote servers)

  4. Review the server logs

Tool Unavailable ​

  1. Confirm that the server has successfully connected

  2. Check tool permission settings

  3. Verify tool compatibility

Configuration Not Working ​

  1. Check configuration file syntax

  2. Confirm scope priority

  3. Restart the CodeBuddy application

Example Configuration ​

Python Tool Server ​

json
{
  "mcpServers": {
    "python-tools": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/tools"
      },
      "description": "Python Toolset"
    }
  }
}

Remote API Server ​

json
{
  "mcpServers": {
    "api-server": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer your-token",
        "X-API-Version": "v1"
       },
      "description": "Remote API Service"
    }
  }
}

Node.js Local Server ​

json
{
  "mcpServers": {
    "node-server": {
      "type": "stdio", 
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      },
      "description": "Node.js MCP Server"
    }
  }
}

Extension Development ​

Creating a Custom MCP Server ​

  1. Choose Implementation Language: Python, Node.js, Go, etc.

  2. Implement MCP Protocol: Use the official SDK or implement it yourself

  3. Define Tool Interfaces: Describe tool functionality and parameters

  4. Handle Requests: Receive and process requests from CodeBuddy

  5. Return Results: Return execution results in MCP format

SDKs and Libraries ​

  • Python: @ModelContextProtocol/python-sdk

  • TypeScript/JavaScript: @ModelContextProtocol/typescript-sdk

  • Other Languages: Refer to official documentation for implementation