mcpx-runtime

# MCPX Runtime > Skill by [ara.so](https://ara.so) — MCP Skills collection. MCPX is an MCP Runtime (gateway) that runs in your development environment. It exposes a unified MCP interface over Streamable HTTP, allowing ChatGPT, Claude, Cursor, Grok, and other AI clients to understand projects, view unified diffs, modify source code, run tasks, collect environment information, and invoke local MCP servers and skills. Development state is persisted in SQLite Remote Sessions, independent of any AI vendor or single `Mcp-Session-Id`. Different clients can query, authorize handoff, and continue the same development work. ## Installation ### From Release (Recommended) Download the binary for your platform from [GitHub Releases](https://github.com/opentokenz/mcpx/releases): ```bash # macOS/Linux curl -L https://github.com/opentokenz/mcpx/releases/latest/download/mcpx-server-$(uname -s)-$(uname -m).tar.gz | tar xz chmod +x mcpx-server sudo mv mcpx-server /usr/local/bin/ ``` ### From Source Requires **Go 1.26.1+**: ```bash git clone https://github.com/opentokenz/mcpx.git cd mcpx go build -o bin/mcpx-server ./cmd/mcpx-server sudo mv bin/mcpx-server /usr/local/bin/ ``` ## Starting the Server ```bash # Basic start mcpx-server # Start with a workspace registered mcpx-server --workspace /path/to/your/project # Check version mcpx-server -version ``` On first run, MCPX creates `~/.mcpx/` (override with `MCPX_HOME`) containing: - `config.yaml` — global configuration (port, auth, security policies, workspaces) - `.mcp.json` — upstream MCP server list (can be empty) - `logs/` — audit logs - `state/mcpx.db` — SQLite database for sessions, changesets, tasks, artifacts - `tasks/` — persistent terminal task logs (mode 0600) - `skills/` — optional skills directory - `oauth-clients.json` — dynamic OAuth client registry (if using OAuth) - `workspaces.example.yaml` — workspace configuration example Default endpoint: `http://127.0.0.1:9090/mcp` (Streamable HTTP only) ## Configuration ### Basic `~/.mcpx/config.yaml` ```yaml server: host: 127.0.0.1 port: 9090 auth: mode: open # or "bearer" or "oauth" # bearer: # tokens: # - env: MCPX_TOKEN workspaces: - name: my-project root: /Users/you/projects/my-app description: Main application workspace security: allow_commands: - npm - go - python - cargo deny_paths: - ~/.ssh - ~/.aws - /etc limits: max_result_bytes: 262144 # 256KB inline result limit max_changeset_files: 100 ``` ### Workspace Configuration Workspaces can be defined in `config.yaml` or separately in `~/.mcpx/workspaces.yaml`: ```yaml workspaces: - name: frontend root: /Users/you/projects/app-ui description: React frontend - name: backend root: /Users/you/projects/app-api description: Go API server - name: docs root: /Users/you/projects/app-docs description: Documentation site ``` ### Upstream MCP Configuration Configure local MCP servers in `~/.mcpx/.mcp.json`: ```json { "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, "postgres": { "command": "uvx", "args": ["mcp-server-postgres"], "env": { "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}" } } } } ``` ## Connecting AI Clients ### ChatGPT Desktop (macOS) 1. Open ChatGPT → Settings → Features → Model Context Protocol 2. Add server: `http://127.0.0.1:9090/mcp` 3. Name: `MCPX Local` ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "mcpx-local": { "transport": { "type": "streamable-http", "url": "http://127.0.0.1:9090/mcp" } } } } ``` ### Cursor Add to Cursor settings: ```json { "mcp.servers": { "mcpx": { "url": "http://127.0.0.1:9090/mcp" } } } ``` ## Key MCP Tools MCPX exposes these tool categories through MCP: ### Workspace Management ```go // List available workspaces { "name": "workspace_list" } // Switch to a workspace { "name": "workspace_switch", "arguments": { "name": "frontend" } } ``` ### Source Code Operations ```go // Inspect project structure { "name": "project_inspect", "arguments": { "action": "tree", "include_hidden": false } } // Search source code { "name": "context_query", "arguments": { "query": "customer phone", "glob": "**/*.vue", "context_lines": 2 } } // Read source files { "name": "source_read", "arguments": { "paths": ["src/views/erp/order.vue"] } } ``` ### Changesets (Diff-First Workflow) ```go // Prepare a changeset { "name": "change_prepare", "arguments": { "draft_id": "fix-login-flow", "changes": [ { "path": "internal/auth/login.go", "action": "update", "old_revision": "sha256:abc123...", "hunks": [ { "old_start": 42, "old_count": 1, "new_start": 42, "new_count": 1, "lines": [ " func Login(user string) error {", "- return legacyLogin(user)", "+ return secureLogin(user)", " }" ] } ] } ] } } // Execute changeset (applies to workspace) { "name": "change_execute", "arguments": { "draft_id": "fix-login-flow" } } // Rollback changeset { "name": "change_rollback", "arguments": { "changeset_id": 42 } } ``` ### Terminal Execution ```go // Short command (inline result) { "name": "command_execute", "arguments": { "command": "go test ./internal/auth", "description": "Run auth package tests" } } // Long-running task { "name": "task_start", "arguments": { "command": "npm run dev", "description": "Start dev server", "persistent": true } } // List tasks { "name": "task_list" } // Stop task { "name": "task_stop", "arguments": { "task_id": "task-uuid" } } ``` ### Environment Information ```go // Get environment snapshot { "name": "environment_get", "arguments": { "sections": ["os", "toolchain", "network"] } } // Take screenshot { "name": "screenshot_capture", "arguments": { "display": 0, "format": "png" } } ``` ### Upstream MCP Proxy ```go // Call upstream MCP server { "name": "mcp_call", "arguments": { "server_name": "github", "tool_name": "create_issue", "tool_args": { "owner": "opentokenz", "repo": "mcpx", "title": "Feature request", "body": "Add XYZ support" } } } ``` ## Remote Sessions MCPX uses persistent SQLite-backed Remote Sessions that survive client reconnects: ```go // Create a session bound to a workspace { "name": "remote_session_create", "arguments": { "workspace_name": "frontend", "description": "Fix customer phone display bug" } } // List sessions { "name": "remote_session_list", "arguments": { "workspace_name": "frontend" } } // Resume a session { "name": "remote_session_attach", "arguments": { "session_id": "session-uuid" } } ``` Sessions track: - Changesets and their history - Terminal tasks and logs - Artifacts (test reports, build outputs) - Confirmation requests - ACL (who can access/modify) ## Workspace Observation Monitor workspace activity from a separate terminal: ```bash # Human-readable format mcpx-server workspace frontend # Machine-readable format mcpx-server workspace --format json --history 200 frontend ``` Example text output: ``` ╭─ #42 · 4f8c2e90 · command_execute │ • Ran go test ./internal/auth │ ↳ Modified login flow and ran tests │ • Read stdout │ ↳ 12 tests passed ╰──────────────────────── ╭─ #43 · 4f8c2e90 · change_execute │ • Edited internal/auth.go │ ↳ internal/auth.go (update) +1 -1 │ -return legacyLogin() │ +return secureLogin() ╰──────────────────────── ``` ## Security ### Authentication Modes ```yaml auth: mode: open # No auth (localhost only) # OR bearer token auth: mode: bearer bearer: tokens: - env: MCPX_TOKEN # Read from env var - value: "static-token-here" # Not recommended # OR OAuth auth: mode: oauth oauth: issuer: https://auth.example.com audience: mcpx-local ``` ### Command & Path Policies ```yaml security: allow_commands: - npm - go - python3 - cargo - make deny_commands: - rm - dd - mkfs allow_paths: - ~/projects/** deny_paths: - ~/.ssh/** - ~/.aws/** - /etc/** semantic_confirmation: enabled: true threshold: critical # or "high" ``` ### Changeset Conflict Detection MCPX validates file revisions before applying changes: ```go // Read returns SHA-256 { "name": "source_read", "arguments": { "paths": ["src/app.go"] } } // Response includes: "revision": "sha256:abc123..." // Prepare must match current revision { "name": "change_prepare", "arguments": { "changes": [{ "path": "src/app.go", "old_revision": "sha256:abc123...", // Must match current "hunks": [...] }] } } ``` If file changed externally, MCPX rejects the changeset. ## Real-World Workflow Example ```go // 1. Agent lists workspaces workspace_list()