Generated CLI and MCP packages

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 4 configuration used by the consumer SDKs. 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.

{
  "version": 4,
  "resources": [
    "collection:orders",
    "collection:customers",
    "relation:orders/customer",
    "operation:orders:approve",
    "function:status:check"
  ],
  "targets": [
    {
      "language": "cli",
      "package": {
        "name": "acme",
        "module": "example.com/acme/cli",
        "version": "0.1.0"
      },
      "output": "generated/cli",
      "agent": {
        "instructions": "Inspect orders before proposing changes. Preserve request_id after uncertainty. Close retained questions when finished.",
        "examples": {
          "orders.related.customer.list": [
            {
              "description": "Read the customer of one order",
              "input": {
                "source": { "where": { "_id": "order-id" } },
                "page_size": 25
              }
            }
          ]
        },
        "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" }
          }
        }
      }
    },
    {
      "language": "mcp",
      "package": {
        "name": "acme-mcp",
        "module": "example.com/acme/mcp",
        "version": "0.1.0"
      },
      "output": "generated/mcp"
    }
  ]
}

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. 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 are keyed by the generated capability name 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 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

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.

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
acme requests recover --request-id approval-42

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:

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. 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. Each collection and relationship exposes 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.

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

{
  "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"
      }
    }
  }
}

Tools use the same command paths joined by dots, for example orders.list and orders.approve. 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://<package>/contract and bijection://<package>/capabilities. Authored prompts are listed through the MCP prompt interface. Each capability also has an offline documentation resource at bijection://<package>/tools/<tool-name> with its description, usage, reviewed examples and complete schemas.

Authenticated remote MCP

Deploy behind HTTPS with an existing OAuth authorization server and a caller-verifying token exchange endpoint:

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:

{
  "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:

{
  "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 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.

Get Started

Use-case atlas

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Generated CLI and MCP packages

Select and generate

Build and distribute binaries

Headless CLI

Local MCP

Authenticated remote MCP

Distribution evidence

​Select and generate

​Build and distribute binaries

​Headless CLI

​Local MCP

​Authenticated remote MCP

​Distribution evidence

Select and generate

Build and distribute binaries

Headless CLI

Local MCP

Authenticated remote MCP

Distribution evidence