MCP (Model Context Protocol) Usage Documentation

Overview

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

Core Concepts

MCP Server

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

MCP Prompts Integration

MCP servers can provide Prompts (prompt templates), which are automatically converted into CodeBuddy's slash commands. When an MCP server is connected:

• Prompts provided by the server are automatically registered as slash commands
• Command name format: /server-name:prompt-name
• Supports dynamic parameters, collecting user input through an interactive interface
• Command execution calls the MCP server's prompts/get interface to retrieve complete content
• Supports real-time monitoring of configuration changes, automatically updating the list of available commands

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 across multiple scopes), the effective priority is: local > project > user

Security Approval Mechanism

MCP servers in the project scope require user approval upon first connection to ensure security. The system displays detailed server information, and users can choose to approve or deny the connection.

Approval in Non-Interactive Mode (-p/--print)

In non-interactive mode (such as when using the -p/--print parameter), since approval cannot be done through the UI, you need to pre-configure allowed MCP servers using the --settings parameter:

# Method 1: Allow all project MCP servers
codebuddy --settings '{"enableAllProjectMcpServers": true}' -p "your prompt"

# Method 2: Allow specific MCP servers
codebuddy --settings '{"enabledMcpjsonServers": ["server-name-1", "server-name-2"]}' -p "your prompt"

Tool Permission Management

MCP tools support a complete permission management system that allows precise control over which tools can be used:

Permission Rule Types

The permission system supports three rule types (ordered by priority):

1. Deny rules (deny) - Block the use of specified tools (highest priority)
2. Ask rules (ask) - Require user confirmation before using tools (overrides allow rules)
3. Allow rules (allow) - Allow tool use without manual approval

MCP Permission Rule Format

Important: MCP permissions do not support wildcards (*)

Server-level Permissions

mcp__server-name

• Matches any tool provided by the specified server
• Server name is the name configured in CodeBuddy

Tool-level Permissions

mcp__server-name__tool-name

• Matches a specific tool from the specified server

Configuration Examples

Approve All Tools from a Server

{
  "permissions": {
    "allow": [
      "mcp__github"
    ]
  }
}

Approve Only Specific Tools

{
  "permissions": {
    "allow": [
      "mcp__github__get_issue",
      "mcp__github__list_issues"
    ]
  }
}

Deny Specific Tools

{
  "permissions": {
    "deny": [
      "mcp__dangerous_server__delete_file"
    ]
  }
}

Configuration Files

Configuration File Locations

Configuration files use a priority mechanism. The system searches for files in priority order and reads the first existing file. When writing, if a file already exists, it writes to the first existing file; if none exist, it creates the highest priority file.

USER Scope

Priority order (highest to lowest):

1. ~/.codebuddy/.mcp.json (recommended)
2. ~/.codebuddy/mcp.json (deprecated)
3. ~/.codebuddy.json (legacy configuration file)

Read rules: The system searches in the above order and reads the first existing file.

Write rules:

• If any of the above files exist, writes to the first existing file
• If none exist, creates ~/.codebuddy/.mcp.json (highest priority)

PROJECT Scope

Priority order (highest to lowest):

1. <project root directory>/.mcp.json (recommended)
2. <project root directory>/mcp.json (deprecated)

Read rules: The system searches in the above order and reads the first existing file.

Write rules:

• If any of the above files exist, writes to the first existing file
• If none exist, creates <project root directory>/.mcp.json (highest priority)

LOCAL Scope

Local scope configuration is actually saved in the user scope configuration file, differentiated by project through the projects field.

File path: ~/.codebuddy.json#/projects/<workspace_path>

#/projects/<workspace_path> uses JSON Pointer syntax to point to a specific location in the JSON document. For detailed information about JSON Pointer, please refer to: https://datatracker.ietf.org/doc/html/rfc6901

Note:

• The system does not merge multiple configuration files within the same scope; it only uses the first existing file

See the configuration file format section below for examples.

Configuration File Format

{
  "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"
        }
      }
    }
  }
}

Note: The type field is optional. If not specified, the system will automatically infer based on the configuration content:

• When the command field is present, infers stdio type
• When the url field is present, infers http type

It is recommended to explicitly specify the type field to ensure configuration accuracy.

Configuration Structure Details

Depending on the transport type, MCP server configurations have different structures:

STDIO Type Configuration

Communication with local processes via standard input/output.

Field	Type	Required	Description
type	string	Yes	Fixed value "stdio"
command	string	Yes	Executable file path or command
args	Array<string>	No	Command line arguments list
env	Object	No	Environment variable key-value pairs

Example:

{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "PYTHONPATH": "/path/to/tools",
    "DEBUG": "true"
  }
}

SSE Type Configuration

Communication with remote services via Server-Sent Events.

Field	Type	Required	Description
type	string	Yes	Fixed value "sse"
url	string	Yes	SSE service endpoint URL
headers	Object	No	HTTP request header key-value pairs

Example:

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

HTTP Type Configuration

Communication with remote services via HTTP streaming.

Field	Type	Required	Description
type	string	Yes	Fixed value "http"
url	string	Yes	HTTP service endpoint URL
headers	Object	No	HTTP request header key-value pairs

Example:

{
  "type": "http",
  "url": "https://mcp.example.com/api/v1",
  "headers": {
    "Authorization": "Bearer secret-token",
    "Content-Type": "application/json"
  }
}

Command Line Usage

Add MCP Server

STDIO Server

# 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

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

HTTP Server

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

Add Server Using JSON Configuration

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

# Add HTTP type server
codebuddy mcp add-json --scope user http-server '{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Add SSE type server
codebuddy mcp add-json --scope project sse-server '{"type":"sse","url":"https://api.example.com/mcp/sse","headers":{"X-API-Key":"your-api-key"}}'

# Add STDIO server with environment variables
codebuddy mcp add-json --scope user python-tool '{"type":"stdio","command":"python","args":["-m","my_mcp_server"],"env":{"PYTHONPATH":"/path/to/tools"}}'

Manage MCP Servers

List All Servers

# List servers for all scopes
codebuddy mcp list

View Server Details

# View specific server information
codebuddy mcp get my-server

Remove Server

# 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 before connecting, ensuring security
• OAuth authorization URLs are validated for security before opening, only supporting http/https protocols

3. Performance Optimization

• Properly configure server timeout durations
• 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 parameters and environment variables
3. Confirm network connectivity (for remote servers)
4. Review server log output

Tool Unavailable

1. Confirm that the server has successfully connected
2. Check tool permission settings
3. Verify tool compatibility

Configuration Not Taking Effect

1. Check configuration file syntax
2. Confirm scope priority
3. Restart the CodeBuddy application

Example Configurations

Python Tool Server

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

Remote API Server

{
  "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

{
  "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 official SDK or implement 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: FastMCP
• TypeScript/JavaScript: @modelcontextprotocol/sdk
• Other Languages: Refer to official documentation for implementation

Configuration Examples

TAPD

codebuddy mcp add --scope user --transport http --header "X-Tapd-Access-Token: TAPD_ACCESS_TOKEN" -- tapd_mcp_http https://mcp-oa.tapd.woa.com/mcp

Chrome Devtools

codebuddy mcp add --scope user chrome-devtools -- npx -y chrome-devtools-mcp@latest

iWiki

codebuddy mcp add --scope user iwiki -- npx -y mcp-remote@latest https://prod.mcp.it.woa.com/app_iwiki_mcp/mcp3

Related Links

• MCP Official Documentation
• MCP GitHub Repository
• CodeBuddy Official Documentation