mcp

MCP - Complete API Reference

Manage Model Context Protocol (MCP) servers, external tools, and AI integrations.

---

Chat Commands

Server Management

/mcp list                                   List configured MCP servers
/mcp status                                 Check server connection status
/mcp add <name> <command>                   Add new MCP server
/mcp remove <name>                          Remove MCP server
/mcp restart <name>                         Restart server

Tool Interaction

/mcp tools                                  List available tools
/mcp tools <server>                         Tools from specific server
/mcp call <server> <tool> [args]            Call a tool directly
/mcp resources <server>                     List server resources

Configuration

/mcp config <server>                        View server config
/mcp config <server> set <key> <value>      Update config
/mcp logs <server>                          View server logs

---

TypeScript API Reference

Create MCP Client

import { createMCPClient } from 'clodds/mcp';

const mcp = createMCPClient({
  // Transport
  transport: 'stdio',  // 'stdio' | 'sse'

  // Server command
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem'],

  // Options
  timeout: 30000,
  retries: 3,
});

Connect to Server

// Connect
await mcp.connect();

// Check status
const status = mcp.getStatus();
console.log(`Connected: ${status.connected}`);
console.log(`Server: ${status.serverInfo?.name}`);
console.log(`Version: ${status.serverInfo?.version}`);

// Disconnect
await mcp.disconnect();

List Tools

// Get available tools
const tools = await mcp.listTools();

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
  console.log(`  Input schema: ${JSON.stringify(tool.inputSchema)}`);
}

Call Tool

// Call a tool
const result = await mcp.callTool({
  name: 'read_file',
  arguments: {
    path: '/path/to/file.txt',
  },
});

console.log(`Result: ${JSON.stringify(result)}`);

List Resources

// Get available resources
const resources = await mcp.listResources();

for (const resource of resources) {
  console.log(`${resource.uri}: ${resource.name}`);
  console.log(`  Type: ${resource.mimeType}`);
}

// Read a resource
const content = await mcp.readResource('file:///path/to/file.txt');
console.log(content);

List Prompts

// Get available prompts
const prompts = await mcp.listPrompts();

for (const prompt of prompts) {
  console.log(`${prompt.name}: ${prompt.description}`);
}

// Get prompt content
const prompt = await mcp.getPrompt('code-review', {
  code: 'function add(a, b) { return a + b; }',
});

console.log(prompt.messages);

MCP Registry

import { createMCPRegistry } from 'clodds/mcp';

const registry = createMCPRegistry({
  configPath: './mcp-servers.json',
});

// Add server
registry.addServer({
  name: 'filesystem',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', '/home/user'],
  env: {},
});

// List servers
const servers = registry.listServers();

// Get server
const server = registry.getServer('filesystem');

// Remove server
registry.removeServer('filesystem');

// Start all servers
await registry.startAll();

// Stop all servers
await registry.stopAll();

---

Popular MCP Servers

Server	Purpose	Install
filesystem	File operations	@modelcontextprotocol/server-filesystem
github	GitHub API	@modelcontextprotocol/server-github
postgres	Database queries	@modelcontextprotocol/server-postgres
brave-search	Web search	@modelcontextprotocol/server-brave-search
puppeteer	Browser automation	@modelcontextprotocol/server-puppeteer

---

Server Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

---

CLI Commands

# List MCP servers
clodds mcp list

# Add MCP server
clodds mcp add filesystem "npx -y @modelcontextprotocol/server-filesystem /home"

# Test server connection
clodds mcp test filesystem

# Remove server
clodds mcp remove filesystem

---

Best Practices

1. Use official servers — Start with well-tested MCP servers
2. Limit file access — Restrict filesystem server to specific directories
3. Secure credentials — Use env vars for tokens, not command args
4. Monitor logs — Check server logs for errors
5. Timeout handling — Set appropriate timeouts for slow operations