> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Directly served MCP surfaces

> Publish selected business tools at an authenticated application endpoint from the same contract as your SDKs

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.

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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](/client/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.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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](/mcp/authentication) 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](/platform-apis/overview#promoting-and-rolling-back-compiled-releases)
to build, inspect, promote and roll back that application artifact. Rollback
preserves current data and accepted business effects. Read the active
installation:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.