Design the self-hosted capability gateway

[ian-pascoe]

Destination

Produce an implementation-ready product and architecture specification, with a staged delivery plan, for a self-hosted gateway that scales from a local single-user setup to multi-user, multi-organization deployments, authenticates organization-scoped MCP Client Principals, and presents MCP, OpenAPI, GraphQL, and Google Discovery Capability Sources through curated Flat MCP Surfaces over stdio and Streamable HTTP.

Notes

• Domain: Capability Gateway. A Capability Source is one configured MCP server, OpenAPI API, GraphQL API, or Google Discovery service. Multiple instances of the same upstream system are distinct Capability Sources.
• Consult /grilling and /domain-modeling for HITL decision tickets. Consult /research for research tickets. Use /coding-standards, /effect-ts, and /codebase-design for architecture work.
• Treat .repos/caplets as a behavioral reference for a near-rewrite, not as a code, configuration, storage, or HTTP API compatibility contract. Use .repos/executor and .repos/effect as additional references.
• Effect v4 is the internal programming model for services, configuration, schemas, errors, resource safety, concurrency, retries, observability, and tests. Promise libraries stay behind adapters.
• One deployment can contain many Accounts and Organizations. Better Auth owns login, account, organization-membership, consent, and OAuth mechanics. Caplets owns capability authorization and organization isolation.
• Clients can connect directly through standard MCP transports. Each Organization has a canonical /orgs/{organization-id}/mcp Streamable HTTP resource and organization-bound authorization.
• An optional new caplets attach <remote-url> bridge can upload a validated, immutable Project Configuration Snapshot, add its Project Context ID to remote requests, and present the resulting remote surface over local stdio. It uses standard OAuth and does not restore legacy Remote Profiles, private login, Project Binding, or file synchronization.
• Project Configuration can define complete remote sources. It cannot request gateway command execution, stdio sources, or arbitrary files. Project Secret Requirements need source-specific Secret Grants to gateway-owned Secret Locators.
• The gateway keeps client authentication separate from Capability Source authentication. A Client Principal never receives a Source Credential.
• The first release exposes enabled operations as ordinary flat MCP tools. A gateway-specific Code Mode or meta-tool endpoint is later work.
• All valid Source Items are exposed by default. Optional include/exclude globs narrow them, with exclude winning. Exact curation may change public names and descriptive metadata or add input restrictions, but it cannot transform values or weaken source contracts.
• Security scope: accounts, organizations, client authentication and authorization, source authentication, external Secret Providers, renewable credential state, URL policy, bounded results, redaction, capability permissions, and authorization of uploaded Project Configuration Snapshots.
• Preserve compatible MCP resources, resource templates, prompts, completion, and logging. API-description sources produce tools.
• Stdio and Streamable HTTP expose the same logical surface when the Organization, Client Principal, and optional Project Context are the same.
• Runtime reload isolates source failures and retains a source's last valid projection when possible.
• Acceptance must cover all four source types, both transports, direct and attached clients, organization isolation, password and external login, project configuration upload, reload and failure isolation, client authorization, authentication redaction, and stable operation names. Performance benchmarks are not required.

Decisions so far

• Research current MCP projection and transport constraints — Preserve MCP primitives and opaque identifiers end to end, and separate modern stateless requests from deployed legacy session behavior.
• Research OpenAPI capability-source constraints — Compile by OpenAPI version, normalize only semantics-preserving details, and require policy or rejection for ambiguous wire contracts.
• Research GraphQL capability-source constraints — Map only exactly coercible query or mutation operations with fixed selections, preserve partial-data errors, and support authenticated or configured discovery fallbacks.
• Research Google Discovery capability-source constraints — Preserve each versioned document's exact method, URI, parameter, schema, authentication, and media contracts; require API-specific evidence for higher-level behavior.
• Define the canonical capability model — Use durable source and item identities, immutable accepted source snapshots, typed item variants, separate runtime health, coded diagnostics, and permission-filtered client surfaces.
• Define the Flat MCP Surface contract — Project immutable permission- and availability-filtered Client Surfaces with stable qualified names, native MCP pagination and change events, preserved MCP primitives, and identical logical behavior over stdio and Streamable HTTP.
• Define the configuration and curation contract — The file-first authority decision was superseded when multi-organization support entered scope; its source and curation rules remain inputs to a replacement decision.
• Research standard MCP authorization and client identity constraints — Use standard OAuth resource-server discovery and audience validation, keep Client Principal identity separate from OAuth client IDs, subjects, scopes, and roles, and remove the private Attach authentication stack.
• Research external secret-provider integration constraints — Keep Vault, Bitwarden, and 1Password provider, locator, lease, cache, error, and trust contracts distinct instead of inventing one false common secret model.
• Define authentication and trust boundaries — Use Better Auth for multi-account and multi-organization login and OAuth, bind every MCP resource and Client Principal to one Organization, separate host hardening from Caplets policy, and support organization-owned or Account-owned Source Credentials.
• Define result, error, and artifact handling — Use a transport-neutral Operation Outcome with exact typed source results, safe structured errors, managed expiring Artifacts, unified cancellation and deadlines, and identical MCP projection over stdio and Streamable HTTP.
• Define organization state authority and administration contract — Use SQL for mutable state, keep host-file source definitions read-only and available through isolated instances in every Organization, support SQLite and clustered PostgreSQL modes, and keep host database operations outside Caplets.
• Define credential-scoped discovery and snapshots — Use credential-isolated Discovery Scopes with independent snapshots and health, exact configuration and credential-generation binding, no fallback or authenticated reuse across owners, and snapshot-pinned invocation.

Not yet specified

• Exact source-adapter delivery slices remain unclear until source-specific contracts and runtime architecture are settled.

Out of scope

• Hosted operation and billing.
• Interactive tool-call approval workflows.
• Legacy Caplets Attach, Remote Profiles, private login, Project Binding, and arbitrary project file synchronization.
• Code, configuration, storage, or HTTP API compatibility with the previous Caplets implementation.
• Desktop applications, marketplaces, native Pi or OpenCode packages, and a public SDK.
• Gateway-specific Code Mode, search, describe, call, or other meta-tool surfaces.
• Arbitrary request and response transformation languages.
• Special GitOps reconciliation, configuration-bundle ownership, and pruning.
• Built-in database backup or restore, logical import or export, and SQLite-to-PostgreSQL transfer.
• Performance benchmarking.