@okfshare/mcp

Model Context Protocol (MCP) server for okfshare - shared, versioned knowledge for AI coding agents.

This stdio MCP server wraps the okfshare CLI so MCP clients (Claude Code, Cursor, opencode, Codex, and any MCP-compatible agent) can search, read, and publish team knowledge bundles as cited context.

Quick start

npx @okfshare/mcp@latest

The server launches npx okfshare@latest under the hood and speaks JSON-RPC over stdio. Authenticate once with npx okfshare@latest setup (or provide OKFSHARE_TOKEN); every tool call then runs against your workspace.

Claude Code

claude mcp add okfshare -- npx @okfshare/mcp@latest

Any MCP client (stdio)

{
  "mcpServers": {
    "okfshare": {
      "command": "npx",
      "args": ["@okfshare/mcp@latest"]
    }
  }
}

Tools

The server keeps the contract navigable by grouping related platform operations:

| Tool | Operations | | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | | okfshare_list, okfshare_search, okfshare_context, okfshare_open, okfshare_diff, okfshare_log, okfshare_validate, okfshare_whoami | Existing retrieval and local validation tools | | okfshare_graph | search, snapshot, neighbors, path, diff, provenance, related | | okfshare_blame | line, semantic | | okfshare_attestations | list, verify, submit | | okfshare_refs | Branch, channel, tag, and release list, get, resolve, create, move, delete | | okfshare_proposals | Share proposal list, plus detail, reviewer, review, comment, check, reopen, merge, reject | | okfshare_roles, okfshare_organizations, okfshare_teams | Workspace access and organization operations | | okfshare_service_accounts | Service accounts and credential lifecycle | | okfshare_audit, okfshare_governance | Audit metadata, policies, holds, and retention inspection | | okfshare_portability_export, okfshare_ops | Portability exports and status/dependencies/SLOs | | okfshare_fork, okfshare_status, okfshare_pull | Confirmed fork creation and local binding status/pull | | okfshare_bindings, okfshare_siem | Workspace role bindings and SIEM webhook destinations | | okfshare_integrity | One-revision verification or bounded cursor-paginated integrity history | | okfshare_share_access | Direct share roles/grants and private-share operation | | okfshare_rulesets | Ruleset CRUD, validation, and single/all-ruleset evaluation | | okfshare_webhooks | Generic product webhook CRUD | | okfshare_domains | Organization domain list/get/create/manual verify/delete | | okfshare_capabilities, okfshare_organization_administrators, okfshare_admin, okfshare_billing | Capability introspection, administrator assignment, operator controls, and billing snapshot |

Schemas use closed JSON objects and enums for operation names. Mutating delete, merge, reopen, transfer, release, revoke, and retention actions require confirm: true; the server maps this to the CLI's explicit --yes flag. Private keys and secret fields are rejected from JSON payloads and removed from CLI output. Service-account credential responses are marked oneTimeCredential: true; the MCP server never stores them.

Refs with a refType use the CLI's plural category position (branches, channels, tags, or releases). Proposal listing is addressed by share id; proposal review and lifecycle operations remain addressed by proposal id. Capability introspection and organization-administrator assignment map directly to the CLI commands. Domain verification accepts only the explicit verificationToken input and does not persist it.

Mutations always require confirm: true, including reviews, comments, ref creation/moves, account changes, webhook changes, and fork/pull operations. For example:

{
  "name": "okfshare_fork",
  "arguments": { "shareId": "team-notes", "confirm": true }
}

Graph and retrieval calls are revision-addressed; return envelopes from the CLI retain their source, revision, and citation fields for agent answers.

All retrieval responses identify the resolved immutable revision, so citations stay auditable.

Environment

• OKFSHARE_TOKEN - optional. Pre-provisioned CLI credential for headless use. Check existence only; never log its value.
• OKFSHARE_CLI - optional. Override the CLI command (default npx okfshare@latest).

Learn more

• Product site: https://okfshare.app
• CLI: https://www.npmjs.com/package/okfshare
• OKF format: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

License

See the repository license.