tencent cloud

SDK MCP Integration

Download
Focus Mode
Font Size
Last updated: 2026-09-30 18:41:49
AI-Translated
Version Requirements: This document applies to CodeBuddy Agent SDK v0.1.24 and later versions.
Feature Status: SDK MCP support is a Preview feature of CodeBuddy Agent SDK.
This document describes how to integrate and use MCP (Model Context Protocol) servers in CodeBuddy Agent SDK to extend custom tools and features for your applications.

Overview

MCP servers allow you to integrate custom tools, resources, and prompts into CodeBuddy Agent SDK. Through the SDK, you can enable these tools programmatically, adding domain-specific features to your AI workflows.

Core Concepts

MCP Server: An independent process or service that provides tools, resources, and prompts.
Tool: An executable function exposed by an MCP server.
Resource: Readable data or files provided by an MCP server.
Prompt: A templated prompt provided by an MCP server.

Supported Transport Types

CodeBuddy Agent SDK supports three communication methods for MCP servers:
Transport Type
Scenario
Description
STDIO
Local tool
Communicate with local processes through standard input and output.
HTTP/SSE
Remote service
Communicate with remote services through HTTP streaming or Server-Sent Events.
SDK MCP
IDE/SDK integration
MCP server registered by an external SDK (such as an IDE extension)

Configuring the MCP Server

mcpServers supports two configuration methods:
1. Object Format: Define server configurations directly in code.
2. File path string: Points to an MCP configuration file (JSON format).

Object Format

Use the mcpServers option to configure MCP servers. The configuration supports STDIO, HTTP, and SSE transport types.
TypeScript:
import { query } from '@tencent-ai/agent-sdk';

const result = query({
prompt: 'Analyze my project structure',
options: {
mcpServers: {
'my-tools': {
type: 'stdio',
command: 'node',
args: ['./mcp-server.js'],
env: {
NODE_ENV: 'production'
}
},
'api-server': {
type: 'http',
url: 'https://api.example.com/mcp',
headers: {
'Authorization': 'Bearer your-token'
}
},
'sse-server': {
type: 'sse',
url: 'https://events.example.com/mcp/sse',
headers: {
'X-API-Key': 'your-api-key'
}
}
}
}
});
Python:
from codebuddy_agent_sdk import query

result = query(
prompt='Analyze my project structure',
options={
'mcp_servers': {
'my-tools': {
'type': 'stdio',
'command': 'python',
'args': ['-m', 'my_mcp_server'],
'env': {
'PYTHONPATH': '/path/to/tools'
}
},
'api-server': {
'type': 'http',
'url': 'https://api.example.com/mcp',
'headers': {
'Authorization': 'Bearer your-token'
}
},
'sse-server': {
'type': 'sse',
'url': 'https://events.example.com/mcp/sse',
'headers': {
'X-API-Key': 'your-api-key'
}
}
}
}
)

File Path Format

You can also pass a path to an MCP configuration file. The configuration file is in JSON format, and its structure is consistent with the CLI --mcp-config parameter.
TypeScript:
import { query } from '@tencent-ai/agent-sdk';

const result = query({
prompt: 'Analyze my project structure',
options: {
mcpServers: './mcp-config.json'
}
});
Python:
from codebuddy_agent_sdk import query

result = query(
prompt='Analyze my project structure',
options={
'mcp_servers': './mcp-config.json'
}
)
Example of a configuration file format (mcp-config.json):
{
"mcpServers": {
"my-tools": {
"type": "stdio",
"command": "node",
"args": ["./mcp-server.js"]
}
}
}
Note:
When the file path format is used, server configurations of the SDK MCP type (type: 'sdk') are not supported. SDK MCP servers are available only in the object format.

Server Configuration Details

STDIO Configuration

STDIO servers communicate with local processes through standard input and output, making them suitable for local tools.
{
type: 'stdio',
command: 'python', // Executable file or command
args: ['-m', 'my_mcp_server'], // Command-line arguments
env: { // Environment variables
PYTHONPATH: '/path/to/tools',
DEBUG: 'true'
}
}
Common Use Cases:
// Python MCP server
{
type: 'stdio',
command: 'python',
args: ['-m', 'fastmcp']
}

// Node.js MCP server
{
type: 'stdio',
command: 'node',
args: ['./server.js']
}

// Local binary file
{
type: 'stdio',
command: '/usr/local/bin/my-tool',
args: ['--config', '/etc/config.yaml']
}

HTTP Configuration

HTTP servers communicate with remote services through HTTP streaming.
{
type: 'http',
url: 'https://mcp.example.com/api/v1',
headers: {
'Authorization': 'Bearer your-token',
'Content-Type': 'application/json'
}
}

SSE Configuration

SSE servers communicate with remote services through Server-Sent Events.
{
type: 'sse',
url: 'https://events.example.com/mcp/sse',
headers: {
'Authorization': 'Bearer your-token',
'X-API-Version': 'v1'
}
}

Permission Management

MCP tools support fine-grained permission control. Through the canUseTool callback, you can determine which tools can be used.

Tool Permission Modes

type PermissionMode =
| 'default' // Ask the user
| 'acceptEdits' // Accept automatic edits.
| 'bypassPermissions' // Skip permission checks (not recommended for production environments)
| 'plan'; // Plan-only mode.

const result = query({
prompt: 'Process data',
options: {
permissionMode: 'acceptEdits',
canUseTool?: (toolCall) => {
// Custom permission check logic
if (toolCall.name === 'dangerous_operation') {
return false;
}
return true;
}
}
});

Permission Control for Specific Tools

options: {
canUseTool: (toolCall) => {
// Block tools from specific servers.
if (toolCall.name.startsWith('mcp__restricted')) {
return false;
}
// Allow specific tools.
if (toolCall.name === 'mcp__github__list_issues') {
return true;
}
// Ask by default.
return null;
}
}

Using MCP Tools

After the MCP server is configured, the Agent automatically discovers the tools provided by these servers and invokes them when needed.

Automatic Tool Discovery

const result = query({
prompt: `
Using the available MCP tools, complete these tasks:
1. Query the database for recent transactions
2. Analyze the results
3. Generate a summary report
`,
options: {
mcpServers: {
'database': {
type: 'stdio',
command: 'python',
args: ['-m', 'db_mcp_server']
}
}
}
});

for await (const message of result) {
if (message.type === 'tool_use') {
console.log(`Tool: ${message.name}`);
console.log(`Arguments: ${JSON.stringify(message.input)}`);
}
}

Processing Tool Results

for await (const message of result) {
if (message.type === 'content') {
console.log('Agent Response:', message.text);
} else if (message.type === 'tool_use') {
console.log(`Executing: ${message.name}`);
} else if (message.type === 'tool_result') {
console.log('Tool Result:', message.content);
}
}

Example: Database Query MCP Server

The following is a complete example that shows how to create and use a database MCP server.

Creating an MCP Server

db_mcp_server.py:
from fastmcp import FastMCP

mcp = FastMCP('database')

@mcp.tool()
def query_database(sql: str) -> str:
"""Execute a SQL query and return results"""
# Implement the Database Query Logic
return f"Query results for: {sql}"

@mcp.tool()
def get_schema(table_name: str) -> str:
"""Get the schema of a specific table"""
# Return the Table Schema
return f"Schema for: {table_name}"

if __name__ == '__main__':
mcp.run()

Using in the SDK

TypeScript:
import { query } from '@tencent-ai/agent-sdk';

async function analyzeData() {
const result = query({
prompt: `
I need to analyze our user activity data.
1. First, check the schema of the users table
2. Query for users active in the last 7 days
3. Provide insights based on the results
`,
options: {
mcpServers: {
'database': {
type: 'stdio',
command: 'python',
args: ['-m', 'db_mcp_server'],
env: {
DATABASE_URL: process.env.DATABASE_URL
}
}
},
permissionMode: 'acceptEdits'
}
});

for await (const message of result) {
if (message.type === 'content') {
console.log('Analysis:', message.text);
}
}
}

analyzeData().catch(console.error);
Python
from codebuddy_agent_sdk import query
import os

async def analyze_data():
result = query(
prompt="""
I need to analyze our user activity data.
1. First, check the schema of the users table
2. Query for users active in the last 7 days
3. Provide insights based on the results
""",
options={
'mcp_servers': {
'database': {
'type': 'stdio',
'command': 'python',
'args': ['-m', 'db_mcp_server'],
'env': {
'DATABASE_URL': os.environ.get('DATABASE_URL')
}
}
},
'permission_mode': 'acceptEdits'
}
)

async for message in result:
if message.get('type') == 'content':
print('Analysis:', message.get('text'))

# Example: Run the Sample
import asyncio
asyncio.run(analyze_data())

Example: API Integration MCP Server

The following example shows how to create an MCP server that connects to multiple APIs over HTTP.

Server Implementation

api_mcp_server.py:
from fastmcp import FastMCP
import httpx
import os

mcp = FastMCP('api-gateway')

async def call_api(method: str, path: str, **kwargs):
"""Helper to call APIs with authentication"""
headers = kwargs.pop('headers', {})
headers['Authorization'] = f"Bearer {os.environ.get('API_TOKEN')}"
async with httpx.AsyncClient() as client:
response = await client.request(
method,
f"https://api.example.com{path}",
headers=headers,
**kwargs
)
return response.json()

@mcp.tool()
async def get_github_repos(username: str) -> dict:
"""Get GitHub repositories for a user"""
return await call_api('GET', f'/github/users/{username}/repos')

@mcp.tool()
async def search_issues(query: str, labels: list[str] = None) -> dict:
"""Search for issues in GitHub"""
params = {'q': query}
if labels:
params['labels'] = ','.join(labels)
return await call_api('GET', '/github/search/issues', params=params)

@mcp.tool()
async def create_slack_message(channel: str, text: str) -> dict:
"""Send a message to Slack"""
return await call_api(
'POST',
'/slack/chat.postMessage',
json={'channel': channel, 'text': text}
)

if __name__ == '__main__':
mcp.run()

Using in the SDK

import { query } from '@tencent-ai/agent-sdk';

async function searchAndNotify() {
const result = query({
prompt: `
1. Search for open issues labeled "bug" and "critical"
2. Get my GitHub repositories
3. Send a summary to the #dev-team Slack channel
`,
options: {
mcpServers: {
'api-gateway': {
type: 'http',
url: 'https://mcp-gateway.example.com/api',
headers: {
'X-API-Key': process.env.API_GATEWAY_KEY,
'X-Request-ID': `req-${Date.now()}`
}
}
},
permissionMode: 'acceptEdits'
}
});

for await (const message of result) {
console.log(message);
}
}

Example: Remote SSE Server

SSE servers are suitable for scenarios that require real-time data streaming or event push.
import { query } from '@tencent-ai/agent-sdk';

async function monitorSystem() {
const result = query({
prompt: 'Monitor system metrics and alert if any threshold is exceeded',
options: {
mcpServers: {
'monitoring': {
type: 'sse',
url: 'https://monitor.example.com/mcp/events',
headers: {
'Authorization': `Bearer ${process.env.MONITOR_TOKEN}`,
'X-Client-ID': 'codebuddy-sdk'
}
}
}
}
});

for await (const message of result) {
if (message.type === 'content') {
console.log('Alert:', message.text);
}
}
}

Error Handling

When handling MCP server connections, monitor the initialization status and identify failed connections:

Checking Server Initialization Status

TypeScript:
import { query } from '@tencent-ai/agent-sdk';

const result = query({
prompt: 'Use my MCP tools',
options: {
mcpServers: {
'my-tool': {
type: 'stdio',
command: 'python',
args: ['-m', 'my_mcp_server']
}
}
}
});

for await (const message of result) {
// Check the MCP server status during initialization.
if (message.type === 'system' && message.subtype === 'init') {
const failedServers = message.mcp_servers.filter(
s => s.status !== 'connected'
);
if (failedServers.length > 0) {
console.warn('Failed to connect:', failedServers);
}
}
// Handle execution errors.
if (message.type === 'result' && message.subtype === 'error_during_execution') {
console.error('Tool execution failed:', message);
}
}
Python:
from codebuddy_agent_sdk import query

result = query(
prompt='Use my MCP tools',
options={
'mcp_servers': {
'my-tool': {
'type': 'stdio',
'command': 'python',
'args': ['-m', 'my_mcp_server']
}
}
}
)

async for message in result:
# Check the MCP server status during initialization.
if message.get('type') == 'system' and message.get('subtype') == 'init':
failed_servers = [
s for s in message.get('mcp_servers', [])
if s.get('status') != 'connected'
]
if failed_servers:
print(f'Failed to connect: {failed_servers}')
# Handle Execution Errors
if message.get('type') == 'result' and message.get('subtype') == 'error_during_execution':
print('Tool execution failed:', message)

References

More Resources

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback