MCP Configuration

The Model Context Protocol (MCP) is an open standard that allows Cosine CLI to connect with external tools, APIs, and data sources. Think of MCP as a USB-C port for AI applications—providing a standardized way to plug in capabilities like database access, file system operations, API integrations, and more.

What is MCP?

MCP (Model Context Protocol) is an open-source standard developed by Anthropic that enables secure, two-way connections between AI applications and external systems. With MCP, you can:

• Access databases - Query PostgreSQL, MySQL, or any database with an MCP server
• Interact with APIs - Connect to GitHub, Slack, Jira, or custom APIs
• File system operations - Read and write files in controlled directories
• Browser automation - Control browsers through specialized MCP servers
• Custom integrations - Build your own MCP servers for proprietary tools

How MCP Works in Cosine CLI

When you configure an MCP server in Cosine CLI:

1. The CLI starts and manages the MCP server process
2. Cosine discovers the tools (functions) exposed by the server
3. When relevant, Cosine can call these tools to perform actions
4. All tool executions require your approval (unless using --auto-accept)

MCP servers run locally on your machine and communicate with Cosine through standardized protocols.

Quick Start

1. Add a Server from the CLI

For most users, the easiest way to add an MCP server is with cos mcp add.

If you already use Claude Code, the workflow is the same: replace claude with cos.

cos mcp add --transport http stripe https://mcp.stripe.com/

For local stdio servers, place -- between the server name and the command you want Cosine to run:

cos mcp add -e API_KEY=xxx my-server -- npx my-mcp-server

2. Start Cosine

cos start

Cosine will automatically discover and connect to your configured MCP servers.

3. Use MCP Tools

Once connected, Cosine can use the MCP tools:

You: List all files in my projects directory
Cosine: I'll list the files for you. [Uses mcp_filesystem tool]

Add MCP Servers with cos mcp add

Use cos mcp add when you want Cosine to save the server for future sessions. The command writes the server configuration to ~/.cosine/mcp.json for you.

Add a Remote HTTP Server

cos mcp add --transport http stripe https://mcp.stripe.com/

Add a Remote HTTP Server with Headers

cos mcp add --transport http corridor \
  https://app.corridor.dev/api/mcp \
  --header "Authorization: Bearer ..."

Add a Local stdio Server

cos mcp add my-server -- npx -y my-mcp-server

Add a Local stdio Server with Environment Variables

cos mcp add --transport stdio -e API_KEY=xxx airtable \
  -- npx -y airtable-mcp-server

Command Rules

• Put Cosine’s flags before the server name
• Use -- before the command for stdio servers
• Use --header for remote HTTP headers
• Use --env or -e for stdio server environment variables

For example:

• cos mcp add --transport http stripe https://mcp.stripe.com/
• cos mcp add --transport stdio my-server -- python server.py --port 8080

Edit the Config File Directly

If you prefer, you can still edit ~/.cosine/mcp.json manually.

For example:

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/projects"]
    }
  }
}

Configuration File Location

MCP servers are configured in:

• macOS/Linux: ~/.cosine/mcp.json
• Windows: %USERPROFILE%\.cosine\mcp.json

cos mcp add writes to the same file.

Transport Types

Cosine CLI supports two transport protocols:

stdio (Standard)

Best for: Local tools, command-line utilities, file system access

The stdio transport spawns the MCP server as a subprocess and communicates over standard input/output.

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/pz/projects"]
    }
  }
}

http

Best for: Remote services, web APIs, already-running servers

The HTTP transport connects to an MCP server running as a web service. Cosine tries streamable HTTP first and falls back to SSE when needed.

{
  "mcpServers": {
    "remote-api": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Configuration Fields

Common Fields

Field	Type	Required	Description
transport	string	No	Transport type: "stdio" or "http". Auto-detected if not specified.
disabled	boolean	No	Set to true to disable this server temporarily.

stdio Transport Fields

Field	Type	Required	Description
command	string	Yes	The executable to run (e.g., npx, node, python, uv).
args	array	No	Arguments passed to the command.
env	object	No	Environment variables as key-value pairs.

HTTP Transport Fields

Field	Type	Required	Description
url	string	Yes	The HTTP endpoint URL for the MCP server.

Managing MCP Servers

Viewing Server Status

In the terminal user interface (TUI), you can see the status of all MCP servers:

1. Press Ctrl+J to open the command palette
2. Select “MCP servers”
3. View the list of configured servers with their status indicators

Restarting Servers

If an MCP server becomes unresponsive:

1. Open the command palette with Ctrl+J
2. Select “MCP servers”
3. Select “Restart MCP servers”

Disabling Servers

To temporarily disable a server without removing it:

{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "disabled": true
    }
  }
}

Next Steps

• MCP Examples - See example configurations for popular MCP servers
• MCP Server Management - Learn about managing and troubleshooting MCP servers
• Configuration - Learn about general CLI configuration