> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/user-guide/mcp-integration.md).

# MCP Integration

> MCP (Model Context Protocol) is a protocol that enables AI agents to access external tools and data sources. Orbitron integrates with MCP servers to extend AI agent capabilities by connecting to various external services like GitHub, Slack, PostgreSQL, and more.

***

## 🔗 What is MCP?

Through the Model Context Protocol, AI agents can:

* Access external APIs and services
* Perform file system operations
* Query databases
* Interact with third-party platforms
* Execute browser automation tasks
* Access more features through extensible tool integration

***

## ⚡ Key Features

### 🔌 1. Three Server Types

Orbitron supports three types of MCP servers:

* **stdio**: Communicates with local processes via standard input/output (e.g., npx commands)
* **sse**: Communicates with remote servers via Server-Sent Events
* **streamable-http**: Communicates via the Streamable HTTP protocol

***

### ✅ 2. Auto-Approval (Planned)

A feature that lets you configure specific tools to run without manual approval each time is planned:

```json
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem"],
    "autoApprove": ["read_file", "list_directory"]
  }
}
```

> **Note**: The autoApprove field is saved in the configuration file, but it is not actually applied in the current version. Support is planned for a future update.

***

## ⚙️ Configuration

### 📁 Configuration File Location

MCP servers are configured in `~/.orbitron.json`:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "type": "stdio"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "type": "stdio"
    },
    "my-remote-server": {
      "type": "sse",
      "url": "https://my-server.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

***

### 📋 Configuration Structure

Each MCP server can have the following properties:

* **command**: Command to execute (for stdio type)
* **args**: Command arguments (for stdio type)
* **env**: Environment variables (key-value pairs, automatically normalized to uppercase)
* **type**: Server type ("stdio", "sse", or "streamable-http")
* **url**: Server URL (for sse type)
* **headers**: HTTP headers (for sse type)
* **disabled**: Whether the server is disabled
* **autoApprove**: Array of tool names to auto-approve

***

## 🖥️ MCP Server Management

### 💻 MCP TUI Provided

Orbitron provides dialogs for managing MCP servers.

***

### 📋 MCP Server List Dialog

**Opening**

Enter `/mcp` to open the dialog.

* **Navigate/Select**: Use `↑`/`↓` arrow keys to move between servers
* `Enter`: Test server connection
* `t`: Toggle server enabled/disabled
* `e`: Edit server configuration
* `d`: Delete server
* `a`: Add new server
* `Esc`: Close dialog

**Server Status Indicators (v0.1.11+)**

The MCP server list dialog TUI displays color-coded status indicators that update in real-time:

* **● Green (ready)**: Server is loaded and ready
* **● Yellow (loading)**: Server is currently loading
* **● Red (failed/timeout)**: Server load failed or timed out
* **● Gray (disabled)**: Server is disabled
* **● Blue (initializing)**: Server is initializing

***

### ➕ MCP Server Add Dialog

**Opening**

Press `a` in the MCP server list dialog (`/mcp`) to open the add server dialog.

**JSON Configuration Input**

```json
// JSON configuration input example
{
  "my-server": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-package"],
    "env": {
      "API_KEY": "your-api-key"
    }
  }
}
```

**Save and Test**

Press `Ctrl+S` to save or `Ctrl+T` to test all servers before saving.

***

### 🌐 Organization Shared MCP Configuration

You can easily view organization MCP configurations registered in Orbitron Web from the terminal.

**Opening**

Enter `/shared-mcps` to display the list of organization shared MCP configurations.

**Features**

* View the list of MCP server configurations shared by your organization
* Select a configuration to copy to clipboard or download as JSON file

> 💡 **Tip**: When you register organization shared MCP configurations in the MCP Management menu of Orbitron Web, all organization members can easily view the same MCP configuration through the `/shared-mcps` command.

***

### ✓ Configuration Validation

When adding or updating servers, Orbitron validates:

* JSON syntax correctness
* Server type (automatically inferred from configuration)
* Required fields for each server type:
  * stdio: requires `command`
  * sse: requires `url`

***

## 🔧 How MCP Tools Work

### ⚙️ Tool Execution Flow

1. AI agent requests to use MCP tool
2. Permission check (if not auto-approved)
3. Client connection reuse or creation
4. Tool execution with retry mechanism
5. Return result to AI agent

***

## 🔐 Security and Permissions

### 🛡️ Permission System

All MCP tool executions require permission approval:

* Prompt displayed to user before tool execution
* Tool name, action, and parameters displayed
* Automatic approval using `autoApprove` is planned for a future release

***

## 🚀 Advanced Features

### 📊 Per-Server Status Tracking (v0.1.11+)

Each server has its own status that updates in real-time:

* Independent status for each server
* Visual feedback in TUI
* Quickly identify problematic servers

***

### 📈 Usage Statistics

Orbitron tracks MCP tool usage:

* Record call count per tool
* Help identify frequently used tools
* Useful for optimization decisions

***

## 🔍 Troubleshooting

### ❌ Server Won't Load

1. Check server status in MCP server list dialog (color-coded indicators)
2. Test server using `Enter` key
3. Verify environment variables are correctly set (must be uppercase)
4. Check logs for detailed error messages
5. Verify required packages are installed (for npx commands)

***

### ⏱️ Timeout Issues

If servers consistently timeout:

* Individual server timeout is 60 seconds
* Overall initialization timeout is 10 seconds (MCPInitTimeout)
* Check network connectivity (for sse type)
* Verify command/URL is correct
* Consider increasing system resources

***

### 🚫 Permission Denied

If tools fail with permission errors:

* Check file system permissions (for file operations)
* Verify API tokens are valid (for service integrations)
* Verify that you approved the request at the permission prompt

***

### 💾 Cache Issues

If tools don't reflect recent changes:

* Cache is automatically invalidated on configuration hash mismatch
* Manually reload servers if needed
* Verify configuration file is properly saved
* Disabled server status is tracked in cache (v0.1.11+)