MCP Protocol

MCP (Model Context Protocol) allows Kuse Cowork to connect to external tool providers, extending the agent's capabilities.

What is MCP?

MCP is a protocol that enables AI agents to discover and use tools from external servers. It provides:

• Dynamic Tool Discovery: Servers advertise available tools
• Standardized Interface: Common format for tool invocation
• Secure Authentication: OAuth and token-based auth

Connecting MCP Servers

Adding a Server

1. Open Settings → MCP

2. Click Add Server

3. Enter server details:

{
  "name": "my-mcp-server",
  "url": "http://localhost:3000",
  "transport": "http"
}

4. Configure authentication if required

5. Click Connect

‍

Server Configuration

‍

Authentication Types

No Authentication

{
  "name": "local-server",
  "url": "http://localhost:3000",
  "transport": "http"
}

‍

Bearer Token

{
  "name": "api-server",
  "url": "https://api.example.com",
  "transport": "http",
  "auth": {
    "type": "bearer",
    "token": "your-api-token"
  }
}

‍

OAuth

{
  "name": "oauth-server",
  "url": "https://service.example.com",
  "transport": "http",
  "auth": {
    "type": "oauth",
    "clientId": "your-client-id",
    "authUrl": "https://service.example.com/oauth/authorize",
    "tokenUrl": "https://service.example.com/oauth/token"
  }
}

‍

Using MCP Tools

Once connected, MCP tools appear automatically in the agent's tool list.

Tool Naming

MCP tools are prefixed with server identifier:

mcp_<server_id>_<tool_name>

‍

Example:

mcp_github_create_issue
mcp_slack_send_message
mcp_database_query

‍

Tool Discovery

The agent automatically discovers tools when:

1. Server connects successfully
2. Server status changes to "Connected"
3. Tools are listed in the agent's context

Tool Invocation

{
  "name": "mcp_github_create_issue",
  "input": {
    "repo": "owner/repo",
    "title": "Bug Report",
    "body": "Description of the bug"
  }
}

‍

Server Status

Status Indicators

Connection Management

• Reconnect: Retry failed connections
• Disconnect: Temporarily disable server
• Remove: Delete server configuration

Building MCP Servers

Server Requirements

MCP servers must implement:

1. Tool List Endpoint: Return available tools
2. Tool Call Endpoint: Execute tool invocations
3. Health Check: Confirm server status

Example Server (Python)

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# Tool definitions
TOOLS = [
    {
        "name": "hello_world",
        "description": "Returns a greeting",
        "inputSchema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"}
            },
            "required": ["name"]
        }
    }
]

@app.get("/tools")
def list_tools():
    return {"tools": TOOLS}

@app.post("/tools/call")
def call_tool(request: dict):
    tool_name = request["name"]
    args = request["arguments"]

    if tool_name == "hello_world":
        return {"result": f"Hello, {args['name']}!"}

    return {"error": f"Unknown tool: {tool_name}"}

@app.get("/health")
def health():
    return {"status": "ok"}

Example Server (Node.js)

const express = require('express');
const app = express();
app.use(express.json());

const tools = [
  {
    name: 'calculate',
    description: 'Performs calculations',
    inputSchema: {
      type: 'object',
      properties: {
        expression: { type: 'string' }
      },
      required: ['expression']
    }
  }
];

app.get('/tools', (req, res) => {
  res.json({ tools });
});

app.post('/tools/call', (req, res) => {
  const { name, arguments: args } = req.body;

  if (name === 'calculate') {
    const result = eval(args.expression); // Use safe-eval in production!
    return res.json({ result: result.toString() });
  }

  res.status(404).json({ error: `Unknown tool: ${name}` });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000);

Protocol Specification

Tool List Response

{
  "tools": [
    {
      "name": "tool_name",
      "description": "What the tool does",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Parameter description"
          }
        },
        "required": ["param1"]
      }
    }
  ]
}

Tool Call Request

{
  "name": "tool_name",
  "arguments": {
    "param1": "value1"
  }
}

Tool Call Response

Success:

{
  "result": "Tool execution result"
}

Error:

{
  "error": "Error message"
}

‍

Use Cases

External API Integration

Connect to external services:

• GitHub: Create issues, PRs, manage repos
• Slack: Send messages, manage channels
• Jira: Create tickets, update status
• Databases: Query and modify data

Custom Tooling

Build project-specific tools:

• Deployment: Trigger CI/CD pipelines
• Monitoring: Check service health
• Documentation: Generate docs from code

Enterprise Integration

Connect to internal services:

• Internal APIs: Access proprietary systems
• Data Sources: Query internal databases
• Automation: Trigger internal workflows

Security Considerations

Network Security

Local Servers Only

Only connect to trusted MCP servers. Malicious servers can execute arbitrary actions.


Token Management

• Store tokens securely
• Use short-lived tokens when possible
• Rotate tokens regularly

OAuth Security

• Verify OAuth redirect URLs
• Use PKCE for public clients
• Validate token scopes

Troubleshooting

Server not connecting

1. Verify URL is correct
2. Check server is running
3. Confirm network accessibility
4. Review authentication config


Tools not appearing

1. Check server status is "Connected"
2. Verify `/tools` endpoint returns valid response
3. Restart Kuse Cowork


Tool calls failing

1. Check tool input matches schema
2. Review server logs
3. Verify authentication is valid


OAuth flow not completing

1. Check redirect URL configuration
2. Verify client ID/secret
3. Confirm token endpoint is accessible


Configuration Storage

MCP server configurations are stored in:

~/.kuse-cowork/settings.db

Table: mcp_servers

Next Steps

• Tools Reference - Built-in tools
• Agent System - How MCP tools are used
• Development Guide - Building MCP servers

‍