About 5 min read

MCP Integration

Karma One supports the Model Context Protocol (MCP), an open standard that allows AI models to securely interact with external tools, data sources, and services. MCP is the backbone of Karma One's extensibility, powering everything from file operations to browser control to system-level automation.

What Is MCP

The Model Context Protocol is a standardized interface between AI models and the tools they use. Think of it as a universal adapter: any tool that implements the MCP specification can be plugged into Karma One and invoked by the AI during a conversation.

Key properties of MCP:

  • Standardized: Tools declare their inputs, outputs, and descriptions in a consistent JSON Schema format
  • Discoverable: The AI can see all available tools and their capabilities at runtime
  • Permissioned: Users control which tools the AI can invoke and under what conditions
  • Composable: Multiple MCP servers can run simultaneously, each providing different capabilities

Architecture

User Prompt
    |
    v
Karma One AI Engine
    |
    v
MCP Router ──> Built-in MCP Servers (file ops, browser, system, etc.)
    |
    └──────> Custom MCP Servers (user-configured)

When you send a message, the AI evaluates whether any tools are needed to fulfill the request. If so, it generates a tool call that the MCP router dispatches to the appropriate server. The server executes the tool and returns the result to the AI, which incorporates it into the response.

Built-in MCP Servers

Karma One ships with several built-in MCP servers that provide core functionality out of the box.

File Operations

Read, write, search, and manage files in your workspace or sandbox.

| Tool | Description | |------|-------------| | file_read | Read the contents of a file | | file_write | Create or overwrite a file | | file_edit | Make targeted edits to an existing file | | file_search | Search file contents using regex patterns | | file_glob | Find files matching a glob pattern |

Browser Control

Automate web browsing with Playwright-powered tools.

| Tool | Description | |------|-------------| | browser_navigate | Open a URL in the browser | | browser_snapshot | Capture the accessibility tree of a page | | browser_screenshot | Take a visual screenshot | | browser_click | Click an element on the page | | browser_type | Type text into a field | | browser_fill_form | Fill multiple form fields at once | | browser_evaluate | Execute JavaScript on the page |

Knowledge Base Search

Query uploaded documents and knowledge bases.

| Tool | Description | |------|-------------| | knowledge_base_search | Search across one or more knowledge bases | | file_upload | Upload a file for processing and retrieval | | file_query | Query a specific uploaded file | | file_status | Check the processing status of an uploaded file |

System Commands (macOS)

Interact with the local operating system on macOS devices.

| Tool | Description | |------|-------------| | mac_screenshot | Capture a screenshot of the desktop | | mac_clipboard_read | Read clipboard contents | | mac_clipboard_write | Write to the clipboard | | mac_notification | Send a system notification | | mac_open_app | Open an application | | mac_open_url | Open a URL in the default browser | | mac_say | Text-to-speech output | | mac_calendar_events | Read calendar events | | mac_mail_send | Send an email via Mail.app | | mac_safari_read | Read Safari tab content | | mac_finder_list | List files in a directory |

Custom MCP Server Configuration

You can connect Karma One to your own MCP servers to extend its capabilities with custom tools.

Adding a Custom MCP Server

  1. Navigate to Settings in Karma One
  2. Open the MCP Servers section
  3. Click Add Server and provide:
    • Name: A human-readable label for the server
    • Transport: Choose stdio (local process) or sse (remote HTTP)
    • Command (stdio): The command to start the MCP server process
    • URL (sse): The endpoint URL for the remote server
    • Environment Variables: Any required env vars (e.g., API keys)

Example: stdio Server

Name: My Custom Tools
Transport: stdio
Command: npx -y @my-org/mcp-server
Environment Variables:
  API_KEY = sk-xxx

Example: SSE Server

Name: Remote Analytics
Transport: sse
URL: https://mcp.my-company.com/sse
Headers:
  Authorization = Bearer sk-xxx

Server Lifecycle

  • Custom MCP servers start automatically when Karma One launches (if configured)
  • Tools from custom servers appear alongside built-in tools
  • If a server crashes, Karma One will attempt to restart it automatically
  • You can enable/disable individual servers without removing their configuration

MCP Tool Invocation Flow

1. User sends a message
2. AI determines which tools (if any) are needed
3. AI generates a tool_use request with the tool name and parameters
4. Karma One validates the request against permission rules
5. The MCP router dispatches the call to the correct server
6. The server executes the tool and returns the result
7. AI receives the tool_result and continues generating the response
8. If multiple tools are needed, steps 3-7 repeat

Permission Controls

Karma One provides granular control over which tools the AI can invoke and when it needs to ask for permission.

Permission Modes

| Mode | Behavior | |------|----------| | Ask Every Time | AI must get user approval before invoking any tool | | Auto-approve Safe | Read-only tools run automatically; write/execute tools require approval | | Full Auto | All tools run automatically without user confirmation |

Per-Tool Permissions

You can override the global permission mode for individual tools:

  • Always Allow: This tool runs without asking
  • Always Ask: This tool always requires confirmation
  • Deny: This tool is blocked entirely

Permission settings are stored locally and never sent to the AI model. The enforcement happens at the MCP router level before any tool call is dispatched.

How Developers Can Extend MCP

Building a custom MCP server lets you bring any capability into Karma One. Common extension patterns include:

Database Queries

Create a tool that runs SQL queries against your database and returns results as structured data.

Internal APIs

Wrap your company's internal APIs as MCP tools so the AI can fetch data from CRM, ERP, or custom systems.

DevOps Automation

Expose deployment scripts, monitoring dashboards, or infrastructure management as tools.

Getting Started with Development

The MCP specification is open and well-documented. A minimal MCP server needs to:

  1. Implement the tools/list method to declare available tools with JSON Schema
  2. Implement the tools/call method to execute tool requests and return results
  3. Support either stdio (stdin/stdout JSON-RPC) or SSE (HTTP Server-Sent Events) transport

Reference implementations are available in TypeScript, Python, Go, and other languages. See the MCP specification for full details.

When building custom MCP tools, provide detailed descriptions and parameter documentation. The AI uses these descriptions to decide when and how to invoke your tools, so clarity directly improves accuracy.