MCP Configuration

The Model Context Protocol (MCP) is an open standard that allows AI assistants to connect to external tools and data sources. Calmo Local Bridge supports MCP servers, enabling you to extend Calmo’s capabilities with documentation lookup, specialized tools, sequential thinking, and more—all integrated into the same workspace.

What is MCP?

MCP provides a standardized way for AI applications to:

Access External Tools - Connect to specialized tools and services
Retrieve Documentation - Fetch up-to-date docs and code examples
Enable New Capabilities - Add sequential thinking, file access, database queries, and more
Extend Context - Give Calmo access to information beyond its training data

MCP servers run locally (stdio) or remotely (http/https) and communicate with Calmo through a standardized protocol.

Welcome Wizard

During initial setup, the Welcome Wizard helps you configure MCP servers:

Step 4 of 4: Configure MCP Servers The wizard shows:

Configured Servers - List of MCP servers discovered in your config
- Server name (e.g., “http”, “stdio”)
- Tool count (e.g., “2 tools available”, “51 tools available”)
- Connection status
About MCP - Information panel explaining the protocol
- “MCP servers let Calmo interact with external tools like databases, cloud providers, and development tools.”
- Learn More About MCP link
Actions:
- Skip for Now - Continue without configuring servers
- Continue - Proceed with the configured servers

You can skip MCP configuration during setup and add servers later via the MCP Servers panel.

Viewing MCP Servers

Server List Panel

The MCP Servers section appears in the left sidebar below Workspaces:

MCP Servers panel showing connected servers

Panel Header:

🔌 MCP Servers              ↻

Servers: 4    Tools: 64

Servers count - Total number of configured servers
Tools count - Total tools across all servers
Refresh icon (↻) - Reload all servers

Server List: Each server shows:

Server name - Configured identifier (e.g., “context7”, “github”)
Status indicator - Green dot = connected, gray = disconnected
Tool count - Number of tools provided (e.g., “2”, “51”)
Expand arrow (>) - Click to view server details

Example:

> 🟢 context7              2
> 🟢 github               51
> 🟢 mastra               10
> 🟢 sequential-thinking   1

Server Detail View

Click on any server name to open its detail panel:

Detail Panel Contents: Server Status:

Server name - Large heading (e.g., “context7”)
Connected badge - Green status indicator

Server Information Section:

Type - Transport type (http or stdio)
Status - Connection state (Connected, Disconnected, Error)
Tools Available - Count of tools this server provides

Available Tools Section:

“2 tools provided by this server” (expandable)
Click to see list of tool names and descriptions

Action Buttons:

Reload Server - Restart this server’s connection
Edit Config - Open mcp.json in the editor

Configuring MCP Servers

Accessing the Configuration

There are two ways to edit MCP configuration: Method 1: From Server Detail Panel

Click on any server in the MCP Servers list
Click Edit Config button in the detail panel

Method 2: From Panel Footer

Scroll to the bottom of the MCP Servers panel
Click Edit Config button

Both methods open the mcp.json file in the center editor panel.

MCP configuration file open in the integrated editor

Configuration File Location:

macOS: ~/Library/Application Support/Calmo Bridge/mcp.json
Windows: %APPDATA%\Calmo Bridge\mcp.json
Linux: ~/.config/Calmo Bridge/mcp.json

Configuration Format

The configuration uses JSON format with an mcpServers object:

{
  "mcpServers": {
    "server-name": {
      // Server configuration
    }
  }
}

Each server is configured with either stdio (local process) or http/https (remote) transport.

Server Types

Stdio Servers

Local processes that communicate via stdin/stdout. Best for npm packages and local tools. Configuration:

{
  "mcpServers": {
    "mastra": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@mastra/mcp-docs-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Required Fields:

Field	Type	Description
`command`	string	Full path to executable (e.g., `/usr/local/bin/npx`)
`args`	array	Command arguments (e.g., `["-y", "@mastra/mcp-docs-server"]`)

Optional Fields:

Field	Type	Description
`env`	object	Environment variables for the process
`disabled`	boolean	Set to `true` to disable without removing

Finding Command Paths:

# macOS/Linux
which npx
# Output: /usr/local/bin/npx

# Windows
where npx
# Output: C:\Program Files\nodejs\npx.cmd

HTTP/HTTPS Servers

Remote servers accessed over the network. Best for cloud-hosted services. Configuration:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "ctx7sk-xxxx-xxxx-xxxx"
      }
    }
  }
}

Required Fields:

Field	Type	Description
`url`	string	Full URL to the MCP server endpoint

Optional Fields:

Field	Type	Description
`headers`	object	HTTP headers (typically for API keys)
`disabled`	boolean	Set to `true` to disable without removing

Example Configurations

Documentation Server (Context7)

Provides up-to-date documentation for any library:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "ctx7sk-xxxx-xxxx-xxxx"
      }
    }
  }
}

Tools Provided:

resolve-library-id - Find the correct library identifier
get-library-docs - Retrieve documentation for any library

Use Cases:

“Show me the React docs for useState”
“How do I use Terraform’s aws_instance resource?”
“Get me examples of using Express.js middleware”

Mastra Documentation

Access Mastra.ai documentation, examples, and migration guides:

{
  "mcpServers": {
    "mastra": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@mastra/mcp-docs-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Tools Provided:

mastraDocs - Access documentation
mastraExamples - Code examples
mastraBlog - Blog posts and tutorials
mastraChanges - Changelog
mastraMigration - Migration guides
…and more

GitHub Integration

Access GitHub repositories, issues, and pull requests:

{
  "mcpServers": {
    "github": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Tools Provided: 50+ tools for repository management, issues, PRs, and more Use Cases:

“List open issues in my repo”
“Create a PR for this branch”
“Show me recent commits”

Sequential Thinking

Enables structured problem-solving through step-by-step reasoning:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "/usr/local/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking"
      ],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Tools Provided:

sequentialthinking - Structured reasoning tool

Use Cases:

Complex debugging
Architecture decisions
Multi-step problem solving

Complete Example

A full configuration with multiple servers:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "ctx7sk-xxxx-xxxx-xxxx"
      }
    },
    "github": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    },
    "mastra": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@mastra/mcp-docs-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    },
    "sequential-thinking": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Managing Servers

Reloading Servers

After editing the configuration, reload servers to apply changes: Reload All Servers:

Click the ↻ refresh icon in the MCP Servers panel header
All servers reconnect with new configuration

Reload Single Server:

Click on the server in the list
Click Reload Server button in the detail panel
That server restarts with updated config

Auto-Reload:

The bridge watches mcp.json for changes
Servers automatically reload when you save the file
No manual reload needed in most cases

Disabling a Server

To temporarily disable a server without removing it:

{
  "mcpServers": {
    "server-name": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "some-server"],
      "disabled": true
    }
  }
}

The server will show as disconnected in the panel but remain in the config.

Removing a Server

To permanently remove a server:

Click Edit Config in the MCP Servers panel
Delete the entire server object from mcpServers
Save the file
The server disappears from the server list

Example:

{
  "mcpServers": {
    "context7": { /* ... */ },
    // Remove this entire block to delete the server
    "server-to-remove": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "old-server"]
    },
    "github": { /* ... */ }
  }
}

Viewing Server Logs

Check server activity and errors in the Activity Log:

Switch to the Activity tab in the bottom panel
Look for MCP-related log entries:

[15:36:34] [MCP Config] Found server: context7 (http)
[15:36:34] [MCP Config] Found server: mastra (stdio)
[15:36:35] [MCP:context7] Connected with 2 tools
[15:36:37] [MCP:mastra] Connected with 10 tools
[15:36:38] [MCP Registry] Active servers: 3

Errors appear with red indicators:

[15:37:12] [MCP:github] Error: spawn /usr/local/bin/npx ENOENT

Popular MCP Servers

Official Servers

Server	Type	Description
@modelcontextprotocol/server-github	Stdio	GitHub API integration (repos, issues, PRs)
@modelcontextprotocol/server-filesystem	Stdio	File system read/write access
@modelcontextprotocol/server-sequential-thinking	Stdio	Structured reasoning and problem-solving
@modelcontextprotocol/server-slack	Stdio	Slack messaging integration
@modelcontextprotocol/server-postgres	Stdio	PostgreSQL database queries

Community Servers

Server	Type	Description
context7	HTTP	Library documentation and code examples
@mastra/mcp-docs-server	Stdio	Mastra.ai documentation and examples

Find more servers at the Awesome MCP Servers repository and modelcontextprotocol.io.

Platform-Specific Configuration

macOS/Linux

Standard stdio server configuration:

{
  "mcpServers": {
    "server-name": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@package/mcp-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Windows

On Windows, npx is a batch script that requires shell access. Wrap with cmd /c:

{
  "mcpServers": {
    "server-name": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@package/mcp-server"
      ]
    }
  }
}

Or use PowerShell:

{
  "mcpServers": {
    "server-name": {
      "command": "powershell",
      "args": [
        "-Command",
        "npx -y @package/mcp-server"
      ]
    }
  }
}

Security Considerations

MCP servers run with your user permissions and may have network access. Only configure servers you trust.

Best Practices:

Review Server Code - Understand what servers do before adding them
Limit Permissions - Some servers request file system or network access
Secure API Keys - Keep API keys private; don’t commit mcp.json to git
Monitor Logs - Watch for unexpected behavior in the Activity Log
Use HTTPS - For remote servers, always use https:// URLs
Validate Sources - Only install servers from trusted repositories

API Key Security:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        // ❌ BAD: Don't commit this to git
        "CONTEXT7_API_KEY": "ctx7sk-real-key-here"
      }
    }
  }
}

Consider using environment variables for sensitive values (support varies by server).

Troubleshooting

Server Won’t Connect

If a server shows disconnected in the panel:

Check the configuration
- Click Edit Config and verify JSON syntax
- Look for typos in server name, command, or URL
- Validate all required fields are present
Verify command path (stdio servers)
```
which npx  # macOS/Linux
where npx  # Windows
```
Use the full path shown in the config.
Check environment (stdio servers)
- Ensure PATH includes necessary directories
- Verify npm packages are installed globally or accessible
Review logs
- Switch to Activity tab
- Look for error messages from the server
- Common errors:
  - spawn ENOENT - Command not found
  - Connection refused - URL incorrect (HTTP servers)
  - Unauthorized - Invalid API key (HTTP servers)
Reload the server
- Click on the server
- Click Reload Server button

Server Connected But No Tools

If a server shows “Connected” but 0 tools:

Wait for initialization - Some servers take 10-30 seconds to load tools
Check stderr - Look in Activity Log for startup errors
Verify package - Ensure the npm package name is correct
Reload - Click Reload Server to try again

API Key Issues (HTTP Servers)

If an HTTP server fails to connect:

Check header format
```
"headers": {
  "CONTEXT7_API_KEY": "your-key-here"
}
```
Header names must match what the server expects.
Verify key validity
- Ensure the API key is active
- Check it has proper permissions
- Test with curl:
  curl -H "CONTEXT7_API_KEY: your-key" https://mcp.context7.com/mcp
Check URL
- Confirm the full endpoint URL
- Ensure it includes /mcp or correct path

Configuration Errors

If you get JSON parsing errors:

Validate JSON syntax
- Use an online JSON validator
- Common mistakes: missing commas, trailing commas, unquoted keys
Check for typos
- mcpServers (not mcpServer)
- Correct quotes (double quotes for JSON)
Escape special characters
- Backslashes in Windows paths: C:\\path\\to\\file
- Or use forward slashes: C:/path/to/file

Server Crashes or Restarts

If a server repeatedly disconnects:

Check logs for error patterns
Update server package
```
npm update -g @package/mcp-server
```
Report to server maintainers with error logs

Next Steps

Workspace Management

Learn about the file browser and workspace organization

CLI Tools Reference

Explore command execution with the integrated terminal

Best Practices

Tips for using MCP servers effectively in your workflow

Troubleshooting

Solutions to common MCP server issues

For assistance with MCP configuration, contact our support team at [email protected].

Get Started

Local Bridge

Integrations

​MCP Configuration

​What is MCP?

​Welcome Wizard

​Viewing MCP Servers

​Server List Panel

​Server Detail View

​Configuring MCP Servers

​Accessing the Configuration

​Configuration Format

​Server Types

​Stdio Servers

​HTTP/HTTPS Servers

​Example Configurations

​Documentation Server (Context7)

​Mastra Documentation

​GitHub Integration

​Sequential Thinking

​Complete Example

​Managing Servers

​Reloading Servers

​Disabling a Server

​Removing a Server

​Viewing Server Logs

​Popular MCP Servers

​Official Servers

​Community Servers

​Platform-Specific Configuration

​macOS/Linux

​Windows

​Security Considerations

​Troubleshooting

​Server Won’t Connect

​Server Connected But No Tools

​API Key Issues (HTTP Servers)

​Configuration Errors

​Server Crashes or Restarts

​Next Steps

Workspace Management

CLI Tools Reference

Best Practices

Troubleshooting

MCP Configuration

What is MCP?

Welcome Wizard

Viewing MCP Servers

Server List Panel

Server Detail View

Configuring MCP Servers

Accessing the Configuration

Configuration Format

Server Types

Stdio Servers

HTTP/HTTPS Servers

Example Configurations

Documentation Server (Context7)

Mastra Documentation

GitHub Integration

Sequential Thinking

Complete Example

Managing Servers

Reloading Servers

Disabling a Server

Removing a Server

Viewing Server Logs

Popular MCP Servers

Official Servers

Community Servers

Platform-Specific Configuration

macOS/Linux

Windows

Security Considerations

Troubleshooting

Server Won’t Connect

Server Connected But No Tools

API Key Issues (HTTP Servers)

Configuration Errors

Server Crashes or Restarts

Next Steps