> ## 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. # Generated CLI and MCP packages > Publish a versioned business CLI and MCP server from the same public contract as your SDKs The `cli` and `mcp` package targets produce standalone Go applications with a Cobra command tree and an MCP server. Both call the application Go SDK. The CLI target shows help without arguments; the MCP target starts STDIO without arguments. Both executables also support `describe`, domain commands and `mcp serve`. Installed binaries require neither Go nor backend source. ## Select and generate Select admitted public resources in the same version 5 configuration used by the [consumer SDKs](/client/javascript/consumer-sdk). Targets share one selected contract. Use a small selection for each agent's work; an exported package grants no authorization to read or invoke its resources. ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} { "version": 5, "resources": [ "collection:orders", "collection:customers", "relation:orders/customer", "operation:orders:approve", "function:status:check" ], "surfaces": { "support": { "instructions": "Inspect orders before proposing changes. Preserve request_id and request kind after uncertainty. Close retained queries when finished.", "tools": { "orders_list": { "capability": "orders.list" }, "orders_get": { "capability": "orders.get" }, "orders_describe": { "capability": "orders.describe" }, "orders_run": { "capability": "orders.run" }, "orders_status": { "capability": "orders.status" }, "orders_result": { "capability": "orders.result" }, "orders_recover": { "capability": "orders.recover" }, "orders_close": { "capability": "orders.close" }, "orders_related_customer_list": { "capability": "orders.related.customer.list", "examples": [ { "description": "Read the customer of one order", "input": { "source": { "where": { "_id": "order-id" } }, "page_size": 25 } } ] }, "orders_approve": { "capability": "orders.approve" }, "orders_approve_preview": { "capability": "orders.approve.preview" }, "orders_approve_propose": { "capability": "orders.approve.propose" }, "orders_approve_submit_proposal": { "capability": "orders.approve.submit-proposal" }, "orders_approve_withdraw": { "capability": "orders.approve.withdraw" }, "requests_list": { "capability": "requests.list" }, "requests_inspect": { "capability": "requests.inspect" }, "requests_recover": { "capability": "requests.recover" }, "requests_close": { "capability": "requests.close" } }, "prompts": { "investigate": { "description": "Investigate an order before proposing changes", "template": "Read order {{order_id}} and explain the proposed next step.", "arguments": { "order_id": "Order to investigate" } } } } }, "targets": [ { "language": "cli", "package": { "name": "acme", "module": "example.com/acme/cli", "version": "0.1.0" }, "output": "generated/cli", "surface": "support" }, { "language": "mcp", "package": { "name": "acme-mcp", "module": "example.com/acme/mcp", "version": "0.1.0" }, "output": "generated/mcp", "surface": "support" } ] } ``` ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} bijection sdk generate --config bijection.sdk.json --url "$BIJECTION_URL" bijection sdk generate --config bijection.sdk.json --frozen --check ``` Each target contains `main.go`, `go.mod`, `contract.json`, `agent.json`, `artifact.json`, documentation, a Dockerfile and an MCP client configuration example. The lock pins the application Go runtime and the CLI/MCP adapter runtime independently. Contributor builds can select `--go-runtime-version` and `--agent-runtime-version`. Building requires Go 1.25 or newer. Generation is offline with `--frozen` and requires no language toolchain. Each tool has a digest covering its selected binding, schemas and examples. `surfaceDigest` also covers the tool inventory, instructions and prompts, independently of the executable name or command usage text. Installed executables validate those identities before execution. The package's `artifact.json` binds generated instructions, reviewed examples, prompt templates, capabilities and schemas. Package versions and artifact identity are independent of executable contract identity. Review the config and lock together. Changing an instruction changes the artifact even when the selected backend contract stays identical. Prompt templates accept explicitly declared string arguments; they execute no business calls. Examples belong to a surface tool and use its complete MCP input envelope. Generation checks them against the exact selected input schema and refuses unknown capabilities, rounded int64 values and invalid argument shapes. Publishers review example values and keep credentials out of them. At most eight examples per capability, 16 KiB per input and 1 KiB per description are allowed. Generated usage templates cover every command; bounded default examples are included where valid. A named surface selects explicit capabilities and MCP tool names; its CLI retains the original command paths. Instructions, prompts and examples are shared by every target referring to that surface. Targets without a surface expose the complete generated capability set. A package supports at most 256 generated tools and 8 MiB of capability metadata. Split larger selections into packages for specific workflows. Names and command paths must be unambiguous. Generation refuses duplicate or reserved paths and resource names that cannot form commands. It never silently renames capabilities. Run `describe` or inspect `agent.json` for the actual names. ## Build and distribute binaries ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} bijection sdk build --config bijection.sdk.json \ --platforms linux/amd64,linux/arm64,darwin/amd64,darwin/arm64 \ --output dist/agents \ --signing-key /private/release-ed25519.pk8.pem ``` `--signing-key` is optional. When supplied, it must be a private Ed25519 PKCS8 PEM file. Build verifies generated sources against the lock and compiles in a temporary copy. It leaves generated sources untouched, disables CGO, and refuses existing release directories. The pinned runtime modules must resolve through your normal Go proxy or repository credentials. Candidate tests seed those modules in an isolated proxy; they do not establish public version availability. Each platform archive contains the executable, selected contract, generated artifact manifest, tool schemas, documentation and resolved module graph. `release.json` records archive hashes, generated artifact digests, runtime pins, contract identity and Go version. `SHA256SUMS` covers release metadata and archives. Optional `release.sig` is a base64 Ed25519 signature over the exact `release.json` bytes; `release.pub` is the base64 public key. Consumers verify using a public key trusted through their release policy, then verify each downloaded archive hash. A key included alongside an archive does not establish trust by itself. Publish these immutable archives through your artifact service. Generation and build do not upload packages. The generated Dockerfile can build a nonroot MCP container with the same pinned runtime dependencies; supply a writable private `/state` volume and runtime credentials when deploying it. The application owner runs the server on its own infrastructure. ## Headless CLI Supply `BIJECTION_URL`, `BIJECTION_TOKEN_FILE` and `BIJECTION_STATE_DIR`, or the corresponding `--url`, `--token-file` and `--state-dir` flags. The token file must be private and regular; it is reread for credential refresh. Never put credentials in generated code, archives, tool arguments or MCP configuration examples. ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} acme describe acme orders approve --schema acme orders approve --examples acme orders list --status open --page-size 25 --format json acme orders get --id order-id --format json acme orders approve --input @approval.json --request-id approval-42 acme requests inspect --request-id approval-42 --kind operation acme requests recover --request-id approval-42 --kind operation ``` Simple equality filters receive flags when names and scalar types permit them. `--input` accepts inline JSON, `@file`, or `-` for stdin. For functions and business operations it supplies the function's arguments. For collection reads and request commands it supplies the complete command input. Additional flags cannot overwrite values already supplied in JSON. Read `--schema` for filters, ordering, cursors and exact selected argument types. Offline `describe`, command help and `--examples` expose generated usage and reviewed examples before authentication. `docs/index.md` links one documentation file per capability, including its exact input/output schemas. For function and operation CLI commands, an example's `input` property goes in `arguments.json`; `request_id` is passed with `--request-id`. Other commands accept the full example input in `--input`. Relationship tools can select the source population before traversal. Filters outside `source` apply to target objects: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} acme orders related customer list --input \ '{"source":{"where":{"_id":"order-id"}},"where":{"name":"Alice"},"page_size":25}' ``` Input and output retain the native wire encoding: int64 uses `{"$integer":"..."}`, bytes use `{"$bytes":"..."}`, and special floating point values use `{"$float":"..."}`. Omission and explicit null remain distinct. Commands return a JSON `result` envelope. Diagnostics are JSON on stderr. Exit code 0 means success, 1 means an error without a retained request identity, and 3 means the diagnostic includes a request identity to inspect. A request identity alone does not prove submission or acceptance. No command prompts interactively. Collection reads return one page of at most 50 rows with `basis`, `next_cursor`, `end` and `complete`. Reuse the same selection with `cursor` to continue. Retained query result tools return one page of the typed `rows` output, defaulting to 25 rows and accepting at most 50. Native execution admission and limits remain authoritative. Unsupported external work returns a refusal; the adapter never provisions compute. Generic request inspection, recovery and close require `kind: "operation"` or `kind: "query"` alongside `request_id`. The kind distinguishes independent native request owners. Collection-specific lifecycle commands and operation-specific recovery already bind that kind. An operation requires an explicit `request_id`. Its original input is persisted before submission. A timeout or dropped connection can leave an accepted operation; inspect or recover the same ID. Preview and propose are generated subcommands. `submit-proposal` accepts an existing request ID and reviewed proposal locator; review and approval remain subject to native authority. `withdraw` addresses the original intention. Generic recovery never creates a replacement operation. Operation output schemas discriminate native states and type receipt/proposal results from the selected operation return contract. Accepted revisions and proposal expiry values remain exact int64 tags; omitted results stay omitted. The full generated capability set for a collection or relationship includes `run`, `status`, `result`, `recover` and `close` for retained query execution. `describe` explains query preparation. `run` uses the selected query and the SDK's native retained request owner; it requires a durable `request_id`. It accepts explicit row/byte budgets and read consistency. External execution additionally requires a version 1 `execution` binding identifying the owner's integration and collection. The adapter provisions no compute. ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} acme orders run --input \ '{"where":{"status":"open"},"request_id":"investigation-42","max_rows":128,"max_bytes":1048576}' acme orders status --request-id investigation-42 acme orders result --request-id investigation-42 --page-size 25 acme orders close --request-id investigation-42 ``` Current computation endpoints can also be selected as public functions; their ordinary function contracts determine their guarantees. There is no separate legacy question resource declaration in consumer packages. Close retained queries when finished. A durable close intent blocks further reads and recovery replays close alone. The journal is isolated by the deployment-verified principal, including owner and incarnation. Private journals currently require POSIX filesystem permissions, atomic hard links and directory synchronization; generated release platforms are Linux and macOS. ## Local MCP ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} { "mcpServers": { "acme": { "command": "/opt/acme/acme", "args": ["mcp", "serve", "--transport", "stdio"], "env": { "BIJECTION_URL": "https://your-deployment.example", "BIJECTION_TOKEN_FILE": "/private/acme/business-token", "BIJECTION_STATE_DIR": "/private/acme/requests" } } } } ``` Named surfaces publish their explicit tool names, such as `orders_list` and `orders_approve`. Unprofiled targets use command paths joined by dots. They declare selected input and output schemas, return structured results plus text JSON, and mark reads conservatively. Tool errors include a machine-readable diagnostic and retained request ID when present. STDOUT contains only MCP protocol messages. Contract and capability resources are available under `bijection:///contract` and `bijection:///capabilities`. Authored prompts are listed through the MCP prompt interface. Each capability also has an offline documentation resource at `bijection:///tools/` with its description, usage, reviewed examples and complete schemas. For a directly served application endpoint, use [native MCP surfaces](/client/native-mcp). ## Authenticated remote MCP Deploy behind HTTPS with an existing OAuth authorization server and a caller-verifying token exchange endpoint: ```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} acme mcp serve --transport http --listen 127.0.0.1:8080 \ --resource-url https://agents.example.com/mcp/acme \ --authorization-server https://identity.example.com \ --token-exchange-url https://identity.example.com/bijection/exchange ``` The adapter publishes OAuth protected-resource metadata at `/.well-known/oauth-protected-resource/mcp/acme`. It refuses missing credentials, cross-origin browser requests and redirects from the exchange service. Each MCP request exchanges its incoming bearer token. The exchange endpoint owns signature, issuer, audience, expiry and delegation validation, and receives: ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} { "subject_token": "incoming MCP access token", "subject_token_audience": "https://agents.example.com/mcp/acme", "resource": "https://your-deployment.example" } ``` After verification and authorized delegation, it returns: ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} { "access_token": "caller-bound Bijection business token", "token_type": "Bearer", "expires_in": 60, "resource": "https://your-deployment.example" } ``` The returned resource must exactly match `BIJECTION_URL`, and `expires_in` must be between 1 and 3600 seconds. The backend verifies the resulting business identity and authority on calls. HTTP serving never reads a shared token file. Tokens stay in request memory; durable journals contain original request custody without credentials. This is an explicit integration with the application's identity owner. Bijection's existing [MCP module](/mcp/overview) remains the owner of installed native MCP definitions, sessions and endpoint-bound delegation. ## Distribution evidence `stack release packages consumer-agents` accepts a frozen configuration with `--config`, `--cli`, `--work`, and `--go`, `--go-runtime` and `--agent-runtime`. It seeds the two candidate modules into an isolated Go proxy, builds each executable twice, checks archive equality, runs independent binaries and connects a separate official MCP client. Receipts retain exact candidate/runtime hashes, source state and tool versions. Controlled protocol tests separately exercise values, bounded reads, uncertain operations, caller isolation, named outputs, close recovery and HTTP identity exchange. These checks establish candidate packaging and adapter behavior. Hosted qualification and real registry publication are separate evidence. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.