Skip to content
ContractSpec
Start here

app.managed-companyos-mcp

Managed MCP server for CompanyOS operations and governed agent access.

appsappv2.0.4experimentalservernode
@lssm-tech/app.managed-companyos-mcp
bun add @lssm-tech/app.managed-companyos-mcp
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

MCP server that exposes Managed CompanyOS operations and resources for tenant onboarding, integration discovery, workflow status, replay, evidence, health probes, and fail-closed Managed Builder evidence tools.

What It Does

  • Hosts a ContractSpec MCP server over Managed CompanyOS contracts (companyos/*).
  • Exposes V1 read/onboarding tools, Builder readiness/replay/evidence/release tools, and one reference resource for the operator copilot.
  • Exposes tenant-safe, read-only fixture resources for Company Brain, temporal graph, experiment/outcome, and provider health projections. These resources require an authenticated tenant match plus an explicit authorization decision and never expose credential references.
  • Resolves the actor from env vars (single-tenant per process) in V1; multi-tenant HTTP transport is deferred to V2.
  • Fails closed until API keys are verified: a configured key yields a role-less user, never an admin, and commands are denied unless reference mode is on outside production. Queries and read-only resources stay available.

V1 Tools

ToolContract
tenant.onboardcompanyos/commands/tenantOnboard.command.ts
tenant.getcompanyos/queries/tenantGet.query.ts
integration.list-providerscompanyos/queries/integrationListProviders.query.ts
workflow.get-statuscompanyos/queries/workflowGetStatus.query.ts
approval.list-pendingcompanyos/queries/approvalReasons.query.ts (stub source until control-plane reuse lands)
replay.get-packetcompanyos/queries/replayGetPacket.query.ts
evidence.get-receiptcompanyos/queries/evidenceGetReceipt.query.ts
health.workercompanyos/queries/healthWorker.query.ts
builder.readiness.evaluatecompanyos/commands/builderReadinessEvaluate.command.ts
builder.evidence.receipt.getcompanyos/queries/builderEvidenceReceiptGet.query.ts
builder.replay.packet.getcompanyos/queries/builderReplayPacketGet.query.ts
builder.release.capsule.getcompanyos/queries/builderReleaseCapsuleGet.query.ts

Read-only projection resources

  • companyos://tenants/{tenantId}/company-brain
  • companyos://tenants/{tenantId}/temporal-graph
  • companyos://tenants/{tenantId}/experiment-outcome
  • companyos://tenants/{tenantId}/provider-health

These are deterministic reference projections only. They perform no writes or network access, fail closed for anonymous/cross-tenant/denied requests, and use only declared package exports.

Environment Variables

  • MANAGED_COMPANYOS_MCP_API_KEY — platform API key (required in production). It is not verified yet, so it identifies a caller but grants no role.
  • MANAGED_COMPANYOS_MCP_TENANT_ID — optional tenant pin for tenant-scoped keys.
  • MANAGED_COMPANYOS_MCP_REFERENCE_MODE — set to 1 to let the deterministic reference bindings run commands (tenant.onboard, builder.readiness.evaluate). Ignored when NODE_ENV=production; any other value keeps commands denied.
  • MANAGED_COMPANYOS_MCP_NAME — override server name (default managed-companyos-mcp).
  • MANAGED_COMPANYOS_MCP_VERSION — override server version (default 0.1.0).

Running Locally

From packages/apps/managed-companyos-mcp:

  • bun run dev
  • bun run start
  • bun run build
  • bun run typecheck
  • bun run test

Architecture

  • src/server.ts boots the MCP server and stdio transport.
  • src/blueprint.ts defines the app blueprint.
  • src/tools.ts installs operation specs through installOp.
  • src/resources.ts exposes the reference workspace resource.
  • src/prompts.ts registers the operator copilot prompt.
  • src/tenant-context.ts resolves the actor and the fail-closed policy gate (decide, createManagedToolDecider).
  • src/smoke.test.ts asserts the registry registers the expected number of tools and that the gate denies commands from an unverified key.

Status

Handlers are deterministic reference bindings for V1. Until lib.auth-os verifies API keys, commands run only in reference mode (MANAGED_COMPANYOS_MCP_REFERENCE_MODE=1, never in production). Builder-specific handlers are live fail-closed evidence tools: they reject raw-looking credentials, report missing provider/webhook refs as blockers, and emit Builder-scoped readiness/replay/receipt/release packets without replacing agent/workflow.

Relationships

THIS PACKAGEapp.managed-companyos-mcp11 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

6 declarations

Declared capabilities

This manifest does not declare a capability catalogue. Use the guide, import map and source to assess the package.

Scripts

  • cleanrm -rf dist
  • lintbun run lint:fix
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • buildbun ../../../scripts/tsdown.mjs
  • devbun ../../../scripts/tsdown.mjs --watch
  • startnode dist/server.js
  • typechecktsgo --noEmit
  • testbun test
  • companyos:builder:mcp-smokebun test src/smoke