Directly served MCP surfaces

This workflow currently requires a source-built CLI and the pinned workspace MCP runtime 0.3.0. These additions have not yet been included in a published CLI or MCP package release. A native MCP surface is served by your Bijection application at /mcp/<name>. The consumer generator supplies typed tools, exact value schemas, reviewed examples, documentation resources and prompts. @bijectionhq/mcp owns the protocol and HTTP transport. The application supplies its access model and session policy. SDKs, CLI binaries, standalone MCP executables and native endpoints can share one selected contract and a named agent surface. Serving a native endpoint requires no Go build, container, token exchange proxy or local request journal.

Select the contract and tools

Use configuration version 5. Package targets are optional for an endpoint-only configuration. The adjacent contract lock retains its own version independently of this configuration format.

{
  "version": 5,
  "resources": ["collection:orders", "operation:orders:approve"],
  "surfaces": {
    "support": {
      "instructions": "Read the order before requesting approval. Preserve request_id and kind after uncertainty.",
      "tools": {
        "orders_list": { "capability": "orders.list" },
        "approve_order": { "capability": "orders.approve" },
        "requests_inspect": { "capability": "requests.inspect" },
        "requests_recover": { "capability": "requests.recover" }
      }
    }
  },
  "mcpServers": {
    "support": { "surface": "support" }
  }
}

Every capability must belong to a selected public resource. Dependencies, including both ends of a relationship, remain explicitly selected. Tool names are authored once. Native names contain at most 64 letters, digits or underscores and begin with a letter; server names are lowercase identifiers of at most 32 characters. A native server publishes at most 32 selected tools. A surface exposing operation submission must include generic inspection and recovery. Retained query creation requires status, result, recovery and close tools. Each tool can declare a description and schema-checked examples. Surface-level prompts and instructions use the same format as agent packages. A standalone cli or mcp target can reference the same surface. Portable business writes use operations. An ordinary mutation or action selected as a surface tool is refused during generation. requests.list enumerates a standalone executable’s private journal and cannot be installed natively; use explicit native request inspection and recovery.

bijection sdk generate --config bijection.sdk.json --url "$DEV_URL"
bijection sdk generate --config bijection.sdk.json --frozen --check

Generation writes owned source under bijection/_generated/consumer_mcp/, with one factory per server and an artifact manifest covering every generated file. It refuses overlapping or unmanaged outputs and participates in the same atomic publication as the language packages and contract lock.

Attach an access policy and mount the routes

Initialize a delegated endpoint with an existing trusted OAuth issuer and an explicit permission ceiling:

bijection mcp init --config bijection.sdk.json \
  --authorization-server https://auth.example.com \
  --permissions 'order:read,order:approve,operation:read,operation:invoke'

Initialization checks for an application access model and a declared @bijectionhq/mcp@0.3.0 runtime. It reports missing or mismatched dependencies; install the runtime and configure access before deployment. It does not create grants. The permissions must exist in your application’s access model. Omission gives an empty ceiling. Initialization creates bijection/mcp.ts and mounts its routes in bijection/http.ts, preserving an existing router’s other routes. An existing application-owned MCP module must explicitly import and include the factories. Configure the issuer in the application’s ordinary authentication configuration before deploying. The generated factory can also use an issued service session. For example, the delegated source produced by initialization is equivalent to:

import { delegatedSessions } from "bijection/sessions";
import { mcpModule } from "@bijectionhq/mcp/bijection";
import { createServer } from "./_generated/consumer_mcp/support";
import { access } from "./access";

export default mcpModule({
  access,
  servers: [
    createServer({
      sessions: delegatedSessions({
        permissions: [
          "order:read",
          "order:approve",
          "operation:read",
          "operation:invoke",
        ],
        maxDurationMs: 30 * 60_000,
      }),
      limits: { requestsPerMinute: 60, pollsPerMinute: 30 },
    }),
  ],
  authorizationServers: ["https://auth.example.com"],
});

The native session policies retain their ordinary authority. Generated selection grants no permission. Every query, operation and response release uses the actual caller and current native authorization. Credentials are absent from generated files, examples and artifacts.

Exact contracts and deployment

Generated hosted and standalone tools use the same tagged native JSON codec for exact integers, bytes and special floating-point values. Missing and explicit null properties remain distinct. The existing compact codec of manually authored native tools is not used for these generated bindings. Each tool publishes its exact input/output schemas, executable binding digest, effects classification, protocol (bijection.consumer-tools.v1), codec (bijection.native-json.v1) and tool digest. Generated manifests pin the MCP runtime, adapter, codec and contract generator; the runtime refuses different pins. A surface digest also binds its instructions, prompts and examples. Packaging names and CLI usage text do not change this portable identity. The installed descriptor adds an installation digest covering the endpoint route, surface, runtime pins, trusted issuers, allowed origins, session policy and request bounds. Query and operation witnesses are checked against the candidate program during native endpoint admission. Selected root object validators, identity domains and row keys are checked against the candidate schema. Relationship witnesses check the selected alias, target, cardinality and supported ordering. Public component operation forwarders are checked against their admitted component, operation and exact contract digest. Current selected metadata and prepared query contracts are also checked before execution. Existing native routes, operation authorization and access-model validation remain required. Generated bindings and their business functions activate together in the application’s compiled release. Use the existing compiled release workflow to build, inspect, promote and roll back that application artifact. Rollback preserves current data and accepted business effects. Read the active installation:

bijection mcp describe support --format json
bijection mcp login https://example.bijection.run/mcp/support --client-id "$CLIENT_ID"
bijection mcp request https://example.bijection.run/mcp/support server/discover \
  --client-id "$CLIENT_ID"

The descriptor includes contract, surface and installation identities, runtime pins, tool count, current admission policy and each generated tool’s binding and digest. release inspect --against returns activeReleaseId and a toolsets array comparing added, removed and changed tool revisions, routes, authentication, session policy, runtimes and execution bounds against the exact target generation. Documentation resources are available at bijection://support/contract, bijection://support/capabilities and bijection://support/tools/<tool-name>.

Drain an installation before removing its endpoint

Attach the existing component admission helper when the endpoint needs durable drain control. Install the MCP component in the application configuration and use its generated reference:

import { installationAdmission } from "@bijectionhq/mcp/bijection";
import { components } from "./_generated/api";

const support = createServer({
  sessions: delegatedSessions({ permissions: ["order:read", "order:approve"] }),
  accepting: installationAdmission(components.mcp),
});

An application-owned administration mutation must authorize its caller before calling components.mcp.lifecycle.setDraining with { draining: true }. The same mutation can resume admission with false. The component owns this flag; serving instances share it. Servers using the same component installation share the drain state. An endpoint that needs no protocol state can still use a different application-owned admission callback. Draining refuses new reads and business submissions. Existing request status, result, recovery, close, proposal submission and withdrawal tools remain available under current authorization. Draining never cancels accepted business work, revives a revoked session or creates a replacement request. bijection mcp describe support --format json includes the endpoint URL, execution bounds and native admission state: accepting, draining, or unavailable when the drain query cannot be read. A custom action callback is reported as evaluated_per_request; operator inspection does not execute that callback inside a query. release inspect --against supplies the target’s active release and compares the retained installation with that target. Outstanding work remains with its original query or operation owner. Inspect retained request references through those authorized APIs, then close query results and allow protocol locator retention to expire before removing the routes and component. Removing the endpoint immediately removes its recovery URL; a code rollback cannot reverse business effects already accepted.

Durable requests and bounded results

Operation invocation requires an explicit stable request_id. Acceptance and native request custody retain its exact contract and input. Reusing an ID with another input is refused. After a lost reply, inspect or recover that same native request, including after the business tool was removed. Generic lifecycle input includes the request kind. Successful responses and uncertain-request diagnostics include a complete request locator. Preserve it for recovery in a different SDK, CLI or MCP delivery:

{
  "request_id": "approval-42",
  "kind": "operation",
  "request": {
    "deployment_id": "deployment-id",
    "incarnation": "deployment-lifetime",
    "request_owner_id": "native-owner-id",
    "request_id": "approval-42"
  }
}

The locator carries no grant. All four fields must match the original namespace and the current authenticated owner. A generated standalone consumer can inspect or recover this locator without its original journal or selected business tool. The Go SDK also exposes workspace.InspectNativeRequest(ctx, kind, reference); the application binding operationRequestResolve authorizes the caller before observing native operation custody. Neither path reconstructs input or submits an operation. Use kind: "query" for retained queries. Native recovery observes the original request and never creates a replacement. An absent request is not proof that another intention should be submitted. Issued sessions retain their offered per-tool revisions; a changed generated tool is refused for that session. Delegated discovery follows the native delegated session’s current contract. Object reads return at most 50 rows per page, defaulting to 25. Relationship source filters run before traversal; outer filters apply to the target. Retained queries expose typed rows results and explicit close. Their creation passes the caller’s declared row/byte bounds, consistency and optional external execution binding to the existing native answer owner. Bijection provisions no compute for an MCP call. Generated surface metadata and each tool output are bounded to 1 MiB. The complete native endpoint admission declaration is also bounded to 1 MiB. Requests are bounded to 512 KiB, and native execution and disclosure limits still apply. Existing-request lifecycle tools remain available while the installation drains; new work is refused.

Inspect refusals and call diagnostics

Generated tools return structured errors with a bounded code, recovery guidance and, when the native scope is known, the original request reference. Transport loss or cancellation after consequential dispatch is uncertain; inspect the same request before taking further action. Refusals never include raw exception messages or business arguments. bijection mcp calls support --format json joins admission with safe tool observations: code, duration, transport correlation and business request ID. Business arguments and results are excluded. Audit observation is best effort; _meta["bijection/observation"]: "unavailable" reports a missing observation without discarding a known native receipt. The descriptor reports whether new work is accepted and whether original-request recovery remains available while draining. Outstanding work remains with its original native request owners. Portable adapter tests and generated-file comparisons do not qualify deployed native authorization, activation, rollback or failure recovery. Qualify those against real deployments when requested.

Get Started

Use-case atlas

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Directly served MCP surfaces

Select the contract and tools

Attach an access policy and mount the routes

Exact contracts and deployment

Drain an installation before removing its endpoint

Durable requests and bounded results

Inspect refusals and call diagnostics

​Select the contract and tools

​Attach an access policy and mount the routes

​Exact contracts and deployment

​Drain an installation before removing its endpoint

​Durable requests and bounded results

​Inspect refusals and call diagnostics

Select the contract and tools

Attach an access policy and mount the routes

Exact contracts and deployment

Drain an installation before removing its endpoint

Durable requests and bounded results

Inspect refusals and call diagnostics