@openbox/mcp-adapter

Pure proxy MCP server that connects IDE runtimes to the OpenBox Bridge API.

Architecture

IDE runtime / external MCP client
    --> MCP transport (repo-local dev server OR remote server)
            --> Bridge API
                  --> Supabase
                  --> Hatchet
                  --> Nango
                  --> native inbox / channel-ingress endpoints
                  --> Langfuse

• Two supported shapes:
  • repo-local stdio adapter, e.g. npm --prefix packages/mcp-adapter run dev
  • remote always-on HTTP MCP server
• Transport depends on the runtime surface (stdio locally, HTTP remotely).
• Recommendation:
  • repo work should use a project-local stdio config
  • remote HTTP is secondary: use it for tenants, external runtimes, or explicit remote validation
• the local worker lane (@openbox/terminal) is adjacent to this package and talks to Bridge API directly; it is not an MCP client
• The adapter is a transport layer only -- all business logic lives in Bridge API.
• Connection mode and inference mode are separate:
  • a local runtime may execute models locally
  • the same runtime may delegate inference remotely through OpenRouter
  • MCP still carries identity, memory, tasks and traces through OpenBox
• Exfiltration Guard and PII masking are enforced at the adapter boundary:
  • locally for repo-local runtimes
  • on the remote MCP server for remote HTTP clients
• remote HTTP MCP clients authenticate to the adapter with Authorization: Bearer; the local stdio lane reads the runtime key from env, then the project-local .openbox/config.json when present, and finally ~/.openbox/config.json; in both cases the adapter authenticates to Bridge API with the configured runtime key

Setup

npx @openbox/mcp-adapter setup --key=<agent-api-key> --project=/path/to/repo

The setup CLI:

1. Validates the API key against Bridge API
2. Detects supported IDE runtimes
3. Creates ~/OpenBox/ workspace with standard structure
4. Writes local stdio IDE config plus, when --project is provided, a project .mcp.json
5. Generates guardrails.yaml with sensible defaults

For repo-local work, the canonical path is the checked-in repo-level .mcp.json.

When setup --project targets a repo that contains packages/mcp-adapter, the generated .mcp.json uses that local adapter over stdio, preferring:

1. node packages/mcp-adapter/dist/terminal.js when the built adapter is present
2. npm --prefix packages/mcp-adapter run --silent dev when only source is present
3. published @openbox/mcp-adapter as the last fallback

Use remote HTTP only when you explicitly want the always-on deployed MCP server.

Canonical Local Path

For this repo, the default project path is:

1. Open the repo with a client that supports project MCP config
2. Let the repo-level .mcp.json start the local adapter over stdio
3. Keep HTTP MCP as an explicit opt-in, not the default repo transport

This keeps project work aligned with the checked-in adapter source and avoids making the remote MCP endpoint the silent default inside the repo.

Remote HTTP Path

Remote HTTP MCP remains supported, but it is not the canonical repo path.

• Use it for tenant environments and external runtimes
• Use it for remote liveness checks and interoperability testing
• Configure it explicitly via IDE/global config or --url=<remote-mcp-url>

Source Of Truth

• Architecture: ADR-013
• Runtime boot contract: runtime-adapters.md
• Onboarding spec: mcp-onboarding
• Repo-level adapter surface: agent-os/adapters/README.md

Current Files

| Path | Purpose | |---|---| | src/index.ts | MCP server implementation (30 tools + 8 resources) | | src/terminal.ts | CLI entrypoint (setup or server mode) | | src/setup.ts | Onboarding flow: IDE detection, workspace creation, config install | | boot-hook.sh | Local boot helper for a compatible IDE runtime | | scripts/stdio-smoke.mjs | Reproducible stdio smoke against the live Bridge API | | scripts/http-smoke.mjs | Reproducible Streamable HTTP smoke against the live Bridge API | | scripts/xai-remote-mcp-smoke.mjs | Reproducible xAI Responses API smoke against the remote OpenBox MCP | | package.json | Build and runtime metadata | | tsconfig.json | TypeScript config |

Tools Summary (28 total + 8 dynamic resources)

| Category | Tools | |----------|-------| | Boot & Identity | openbox_boot, openbox_list_agents, openbox_assume_role | | Memory | openbox_get_memory, openbox_save_memory (PII masked), openbox_search_memory — with scope and optional user/session narrowing | | Tasks | openbox_list_tasks, openbox_create_task, openbox_update_task, openbox_run_task, openbox_delegate_task | | Goals | openbox_list_goals, openbox_get_goal, openbox_create_goal, openbox_update_goal, openbox_close_goal | | Workflows | openbox_trigger_workflow, openbox_list_workflows, openbox_get_workflow, openbox_create_workflow, openbox_update_workflow, openbox_validate_workflow, openbox_get_workflow_runs | | Tracing | openbox_trace | | Files | openbox_read_file (tracked), openbox_list_files | | Security | openbox_revoke_current_key, openbox_doctor (self-test) | | Diagnostics | openbox_diagnostics | | Host | openbox_host_docker_ps, openbox_host_docker_logs, openbox_host_system_status, openbox_host_exec |

Reality check:

• the adapter exposes openbox_assume_role
• the Bridge contract for role switching is X-Agent-Id + POST /auth/assume-role
• the OpenBox repo implements that path locally; live availability depends on the deployed backend revision

Runtime Notes

• Config source precedence: OPENBOX_API_KEY / API_KEY env, then project-local .openbox/config.json, then ~/.openbox/config.json
• API key env aliases: OPENBOX_API_KEY or API_KEY
• Supported URL order: internalBaseUrl / OPENBOX_INTERNAL_BASE_URL first when present, then baseUrl
• Project repo work should prefer .mcp.json + local stdio; mcpUrl is mainly for explicit remote HTTP installs
• Local policy source: guardrails.yaml in the project root
• A local subagent is a child run, not a sovereign OpenBox agent
• Loading another identity with openbox_boot is valid for context hydration
• Canonical parallel agent execution still goes through dispatch + real runtimes
• openbox_diagnostics verifies /boot, /agents, /tasks, /memory, version compatibility, host access and guardrails state
• openbox_doctor runs comprehensive self-tests including exfiltration guard and PII masking
• Dynamic MCP resource templates:
  • openbox://agent/{agent_id}/identity
  • openbox://agent/{agent_id}/memory{?scope,user_id,session_id,limit,offset}
  • openbox://agent/{agent_id}/tasks{?status,limit,offset}
  • openbox://workflow/{workflow_id}
  • openbox://workflow/{workflow_id}/runs{?status,limit,offset}
• stdio mode uses newline-delimited JSON-RPC, not Content-Length framing
• Reproducible smoke: npm run smoke:stdio / npm run smoke:stdio:taskflow / npm run smoke:http

Security Features

Exfiltration Guard

Detects and blocks attempts to upload sensitive data:

| Sensitivity | Patterns | Action | |-------------|----------|--------| | Critical | Private keys, API tokens, cloud credentials | BLOCKED | | Secret | Passwords, API secrets, access tokens, JWTs | BLOCKED | | PII | DNI/NIE, email, phone, credit card | AUTO-MASKED |

PII Masking

| Pattern | Mask | |---------|------| | DNI espanol (12345678A) | [DNI_MASKED] | | Email ([email protected]) | [EMAIL_MASKED] | | Telefono ES (+34 612 345 678) | [PHONE_MASKED] | | Tarjeta credito | [CARD_MASKED] |

Guardrails for Workflows

workflows:
  require_human_approval:
    - "sdr-pipeline"
    - "dispatch"
  local_execution_only:
    - "feature-lifecycle"
  deny:
    - "deprecated-workflow"

File System Security

• Project folder isolation: cannot read/list files outside project folder
• Guardrails integration: respects ignore_patterns and readonly_patterns
• Session tracking: file reads tracked for 5 minutes TTL

Commands

npm install
npm run build
npm run dev
npx @openbox/mcp-adapter setup --project /path/to/project
npm run smoke:stdio
npm run smoke:stdio:taskflow
npm run smoke:http
XAI_PREFLIGHT_ONLY=1 npm run smoke:xai
XAI_API_KEY=... npm run smoke:xai

xAI Remote MCP Smoke

Use this when you want to verify that Grok can consume the live OpenBox MCP via xAI's Remote MCP support.

Environment variables:

• XAI_API_KEY - required for the full xAI call
• XAI_MODEL - optional, defaults to grok-4.20-beta-latest-non-reasoning
• XAI_BASE_URL - optional, defaults to https://api.x.ai/v1
• OPENBOX_MCP_URL - optional, defaults to https://mcp.example.com/mcp
• OPENBOX_ALLOWED_TOOL_NAMES - optional CSV, defaults to openbox_diagnostics
• OPENBOX_MCP_AUTH - optional full Authorization header value for the MCP server
• OPENBOX_MCP_EXTRA_HEADERS - optional JSON object with extra MCP headers
• XAI_INPUT - optional custom prompt sent to Grok

Examples:

# Verify only that the remote MCP endpoint is alive and answers initialize
XAI_PREFLIGHT_ONLY=1 npm run smoke:xai

# Full xAI -> Remote MCP -> OpenBox check
XAI_API_KEY=... \
OPENBOX_ALLOWED_TOOL_NAMES=openbox_diagnostics \
npm run smoke:xai

Rules

• Keep this package as a transport adapter only.
• No Supabase client, no service role key, no product state cache.
• If a capability belongs to OpenBox business logic, implement it in Bridge API, not here.
• Exfiltration Guard is enforced at the adapter level -- cannot be bypassed by Bridge API.