smashimo/oh-my-pi

Fork 0

Files

T

can1357 31afd70edc docs(coding-agent): update MCP guide for smithery commands and sse transport

2026-03-03 04:51:13 +01:00

10 KiB

Raw Blame History

MCP Server Management Command Guide

Complete guide for the /mcp command in oh-my-pi.

Overview

The /mcp command provides interactive management of Model Context Protocol (MCP) servers. It allows you to add, remove, list, and test MCP servers through a user-friendly command-line interface.

Commands

`/mcp` or `/mcp help`

Shows help text with all available commands.

`/mcp add`

Launch interactive wizard to add a new MCP server.

Features:

Step-by-step guided setup
Real-time validation
Three authentication methods
User or project-level configuration
Automatic connection testing

Wizard Flow:

Server Name - Unique identifier (letters, numbers, dash, underscore, dot only)
Transport Type - Choose stdio/http/sse
Configuration:
- stdio: Command + optional arguments
- http/sse: Server URL
Authentication - Three options:
- None (for local/trusted servers)
- OAuth (web-based authentication)
- Manual API key/token
Scope - User-level (~/.omp/mcp.json) or project-level (.omp/mcp.json)
Confirmation - Review and save

`/mcp list`

List all configured MCP servers with connection status.

Output:

Server name
Connection status (connected/not connected)
Transport type [stdio/http/sse]
Organized by scope (user-level vs project-level)

`/mcp remove <name>`

Remove an MCP server from configuration.

Behavior:

Disconnects server if currently connected
Removes from config file
Reloads MCP manager
Shows confirmation message

`/mcp test <name>`

Test connection to an MCP server.

Features:

Creates temporary test connection
Lists server info and version
Shows available tools (up to 10)
Disconnects after test
Provides helpful error messages

`/mcp auth <name>`

Reauthorize OAuth for an existing MCP server.

`/mcp smithery-search <keyword> [--scope project|user] [--limit <1-100>] [--semantic]`

Search Smithery registry and deploy a result from an interactive picker.

Behavior:

Queries Smithery (registry.smithery.ai)
Matches by display name and qualified name by default
Use --semantic to keep raw Smithery results/ranking (no local filtering)
Shows a keyboard-selectable list of matches
Prompts for local server name before deploy (default generated from registry name, editable)
Creates/reuses a Smithery Connect connection and handles provider auth via Smithery when required
Deploys selected server to project or user config
Immediately triggers MCP reload so tools become available in runtime
If Smithery returns auth/rate-limit errors, prompts for Smithery login and retries automatically

`/mcp smithery-login`

Configure Smithery authentication for Smithery commands.

Supported flows:

Browser-assisted CLI auth flow (default)
Manual API key entry in parallel; whichever completes first proceeds

API key is cached in ~/.omp/agent/smithery.json.

`/mcp smithery-logout`

Remove cached Smithery API key from ~/.omp/agent/smithery.json.

Authentication Methods

1. No Authentication

For local or trusted MCP servers that don't require credentials.

Use cases:

Local filesystem servers
Development/testing servers
Internal network servers

Configuration: No auth fields in config

2. Manual API Key/Token

Environment Variable (for stdio servers)

{
  "type": "stdio",
  "command": "npx",
  "args": ["mcp-server"],
  "env": {
    "API_KEY": "sk-..."
  }
}

Supports shell commands:

{
  "env": {
    "API_KEY": "!op read op://vault/mykey"
  }
}

HTTP/SSE Header (for http/sse servers)

{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer sk-..."
  }
}

Automatic Bearer prefix: If header is "Authorization" and value doesn't start with "Bearer ", it's added automatically.

3. OAuth Flow

Full OAuth 2.0 support with PKCE:

Authorization Code flow
PKCE (Proof Key for Code Exchange) for enhanced security
Automatic browser launch
Local callback server
Secure token storage in agent.db

OAuth Configuration:

Authorization URL: OAuth authorize endpoint
Token URL: OAuth token endpoint
Client ID: Your OAuth client identifier
Client Secret: Optional (for flows requiring it)
Scopes: Space-separated permissions (optional)

Token Storage: Tokens are stored securely in ~/.omp/agent.db and referenced by credential ID:

{
  "type": "http",
  "url": "https://api.example.com/mcp",
  "auth": {
    "type": "oauth",
    "credentialId": "mcp_oauth_1707409234567_abc123def"
  }
}

Token Injection:

HTTP/SSE servers: Added to Authorization header as Bearer <token>
stdio servers: Added to OAUTH_ACCESS_TOKEN environment variable

Configuration Files

User-level: `~/.omp/mcp.json`

Global configuration available to all projects.

Project-level: `.omp/mcp.json`

Project-specific configuration (usually in project root).

Example Configuration

stdio server with API key:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/data"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

HTTP/SSE server with OAuth:

{
  "mcpServers": {
    "external-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "auth": {
        "type": "oauth",
        "credentialId": "mcp_oauth_1707409234567_abc123def"
      }
    }
  }
}

Error Messages & Troubleshooting

Common Errors

"Server name can only contain letters, numbers, dash, underscore, and dot"

Server names must be alphanumeric with limited special characters
Maximum 100 characters

"Invalid URL format (must start with http:// or https://)"

URLs for HTTP/SSE servers must include protocol
Example: https://api.example.com/mcp

"Server already exists"

A server with this name is already configured
Use /mcp list to see existing servers
Choose a different name or remove the existing server first

"ECONNREFUSED"

Server is not running or URL/port is incorrect
Check server is started
Verify URL and port number

"401" or "403"

Authentication failed
Check API key/token is correct
For OAuth, re-authenticate

"timeout"

Server is slow or unresponsive
Try increasing timeout in config
Check network connection

Tips

Test before committing: Use /mcp test <name> after adding a server
Start simple: Begin with no authentication, add auth later if needed
Check logs: Server errors often indicate configuration issues
Validate URLs: Ensure URLs are accessible (try in browser first)
Shell commands: Use !op read for password manager integration

Workflow Examples

Adding a Local Filesystem Server

/mcp add
→ Name: "docs"
→ Transport: stdio
→ Command: npx
→ Args: -y @modelcontextprotocol/server-filesystem /home/user/docs
→ Auth: No authentication
→ Scope: Project level
→ Confirm: Yes

Adding an API Server with OAuth

/mcp add
→ Name: "external-api"
→ Transport: http or sse
→ URL: https://api.example.com/mcp
→ Auth: OAuth flow
→ Authorization URL: https://auth.example.com/oauth/authorize
→ Token URL: https://auth.example.com/oauth/token
→ Client ID: your_client_id
→ Client Secret: (leave empty if PKCE-only)
→ Scopes: read write
→ Confirm OAuth config
→ [Browser opens for authentication]
→ Scope: User level
→ Confirm: Yes

Adding an HTTP/SSE Server with API Key

/mcp add
→ Name: "api-server"
→ Transport: http or sse
→ URL: https://api.example.com/mcp
→ Auth: Manual API key/token
→ API Key: sk-1234567890abcdef
→ Location: HTTP/SSE header
→ Header Name: Authorization
→ Scope: User level
→ Confirm: Yes

Testing and Managing

# List all servers
/mcp list

# Test a server
/mcp test docs

# Remove a server
/mcp remove docs

Best Practices

Use project-level config for project-specific servers
- Keep project dependencies in project
- Easier to share with team
Use user-level config for personal/global servers
- Credentials stay private
- Available across all projects
Secure sensitive data
- Use OAuth when available
- Use shell commands for API keys: !op read op://vault/key
- Never commit .omp/mcp.json files with plain API keys to version control
Name servers descriptively
- Use purpose-based names: "github-tools", "docs-search"
- Avoid generic names: "server1", "test"
Test after adding
- Always run /mcp test <name> after adding a server
- Verify tools are accessible
- Check authentication works

Advanced Features

Shell Command References

Any environment variable or header value can reference a shell command:

{
  "env": {
    "API_KEY": "!op read op://vault/mcp-key"
  }
}

The command is executed once and cached for the session.

Automatic Token Refresh

OAuth tokens are automatically refreshed when needed (not yet implemented, but infrastructure is in place).

Connection Pooling

MCP Manager maintains persistent connections to servers for better performance.

Limitations

No inline editing: To modify a server, remove and re-add it
No bulk operations: Servers must be managed individually
No server templates: Each server configured from scratch

Files Modified

packages/coding-agent/src/mcp/config-writer.ts - Config file I/O
packages/coding-agent/src/mcp/oauth-flow.ts - OAuth authentication
packages/coding-agent/src/mcp/manager.ts - Added auth resolution
packages/coding-agent/src/modes/controllers/mcp-command-controller.ts - Command routing
packages/coding-agent/src/modes/components/mcp-add-wizard.ts - Interactive wizard
packages/coding-agent/src/sdk.ts - Auth storage integration

API Reference

For programmatic access, see:

MCPManager.setAuthStorage() - Set auth storage for OAuth resolution
validateServerName() - Validate server names
addMCPServer() - Add server to config file
removeMCPServer() - Remove server from config file
getMCPConfigPath() - Get config file path

10 KiB Raw Blame History