MCP Connector

What This Does

The MCP connector exposes Bombyx memory and dynamic Brain Wiki tools through JSON-RPC.

Use it when your agent, IDE, or local automation already supports Model Context Protocol. Use the REST API when you want normal HTTP endpoints with simpler request shapes.

Before You Start

You need:

A btx_... bearer token
The MCP URL
A connector with the right memory capabilities

Production MCP URL:

https://bombyxlabs.com/app/api/tool-connectors/mcp

Codex Config Example

Store the token in a secret or environment variable named BOMBYX_MCP_TOKEN.

[mcp_servers.bombyx]
url = "https://bombyxlabs.com/app/api/tool-connectors/mcp"
bearer_token_env_var = "BOMBYX_MCP_TOKEN"

Tools

The MCP server exposes these tools:

Tool	What it does
`bombyx_status`	Checks connector identity and capabilities
`bombyx_memory_search`	Searches organization memory
`bombyx_memory_save`	Saves tool-private or organization-internal memory
`bombyx_memory_propose`	Creates a reviewed memory proposal
`bombyx_memory_report_usage`	Reports which recalled memory items were used or ignored
`bombyx_brain_wiki_list`	Lists current Brain Wiki pages allowed for the connector
`bombyx_brain_wiki_get`	Returns one current page with its exact replacement hashes
`bombyx_brain_wiki_propose_change`	Proposes a reviewed complete-page replacement without publishing it
`bombyx_ai_ops_work_list`	Lists capability-matched work with reclaimable expired leases
`bombyx_ai_ops_work_claim`	Atomically claims one work item with an exact run key and lease
`bombyx_ai_ops_work_package`	Loads the bounded project, policy, brief, work, and lease package
`bombyx_ai_ops_work_heartbeat`	Renews a live lease owned by the current worker run
`bombyx_ai_ops_run_start`	Starts or rereads the durable AgentRun for claimed work
`bombyx_ai_ops_result_submit`	Records a verified completion, block, failure, verification hold, or release
`bombyx_ai_ops_judgment_request`	Sends a high-risk or missing-information decision to the overseer inbox
`bombyx_ai_ops_project_brief`	Returns the latest concise project brief
`bombyx_ai_ops_artifact_register`	Registers artifact metadata and checksum without accepting the artifact body
`bombyx_ai_ops_usage_report`	Records requested tier, actual model, tokens, latency, and estimated cost
`bombyx_ai_ops_manager_plan_submit`	Validates and applies a strict organization-scoped manager plan
`bombyx_ai_ops_projects_sync`	Idempotently imports a stable project target as dormant
`bombyx_ai_ops_manager_claim`	Claims one dispatched project-manager item with an exact run key
`bombyx_ai_ops_manager_package`	Loads the claimed manager input, policy hash, target, and output schema
`bombyx_ai_ops_manager_result_submit`	Applies a strict manager result only when its exact model and reasoning match the confirmed primary or fallback route
`bombyx_ai_ops_session_register`	Registers an immutable Codex thread/turn and exact confirmed primary or fallback model route for one organization-owned project
`bombyx_ai_ops_session_heartbeat`	Reports liveness for the exact registered Codex session
`bombyx_ai_ops_session_event`	Records a concise session lifecycle event without raw transcript bulk
`bombyx_ai_ops_session_result_submit`	Idempotently completes or fails an explicitly adopted Codex task with bounded evidence
`bombyx_ai_ops_session_review_submit`	Idempotently records bounded findings and exact correction instructions for a completed session
`bombyx_operator_opportunity_upsert`	Creates or updates an opportunity and suggested draft
`bombyx_operator_authorizations_list`	Lists member-approved actions for the connector
`bombyx_operator_authorization_claim`	Atomically claims one approved action
`bombyx_operator_authorization_revalidate`	Revalidates a claim immediately before submission
`bombyx_operator_authorization_complete`	Records a visibly verified public action
`bombyx_operator_authorization_block`	Records a hard execution blocker
`bombyx_operator_authorization_verification_required`	Quarantines an uncertain publication result
`bombyx_operator_authorization_release`	Releases an unused claim back to the queue
`bombyx_operator_learning_evidence_list`	Lists unprocessed member-approved user revisions and their draft history
`bombyx_operator_learning_context`	Returns active Assistant Coaching for future drafting
`bombyx_operator_learning_apply`	Atomically records evidence decisions, activates coaching, and creates reviewable Brain proposals

bombyx_operator_opportunity_upsert accepts backward-compatible public review context v1 and the thread-first v2 contract. New Reddit reply and comment targets must send v2, including the exact source post and target-comment permalink, bounded related public comments, and a semantic value_add. The nested platform and exact target permalink must match the top-level executable platform and canonical_url. Only distinct_contribution may be submitted as member-ready review work. URLs in v2 must use HTTPS; Bombyx computes and returns the canonical aggregate context_hash when the opportunity is normalized.

Manager work-item dependencies use another work item’s idempotency key. When a person has just approved an exact judgment included in the bounded manager package, the manager may instead use judgment:<id> as a satisfied planning prerequisite. Bombyx validates the organization, project, approval status, and exact input snapshot. This reference never authorizes protected execution, which receives a new work-item-specific judgment. An exact existing work idempotency key takes precedence if it matches the judgment:<id> shape.

The bounded manager package includes concise details for changed terminal work: durable outcome, changes, verification, blockers, and the latest strict Codex session result. Raw terminal output and transcripts remain excluded.

Dynamic Brain Wiki

Brain Wiki pages are derived from each organization’s current compiled Brain, so topic keys and page counts vary by organization and can change after a rebuild. Call bombyx_brain_wiki_list before selecting a page. Use bombyx_brain_wiki_get for the complete current body and these concurrency fields:

generation_uuid
bucket_artifact_hash
display_body_hash

To suggest a change, the connector must have memory_propose. Send a complete replacement body with all three current hashes and a unique idempotency_key to bombyx_brain_wiki_propose_change. Bombyx rejects stale hashes. The result remains pending until an authorized organization member approves it. The tool cannot publish, approve, restore, or bypass Brain audience and source grants.

JSON-RPC Example

curl https://bombyxlabs.com/app/api/tool-connectors/mcp \
  -H "Authorization: Bearer btx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Example response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "bombyx_status",
        "description": "Check the Bombyx connector identity and capabilities."
      }
    ]
  }
}

Explicitly Adopted Codex Tasks

Inventory sync never adopts an existing Codex task. A Bombyx organization manager must select Adopt task for an active project and provide the task’s stable thread ID. A project can have one active writing worker or fixer, while read-only researchers may run concurrently.

The connector then registers the adopted session with bombyx_ai_ops_session_register. That first call binds the connector and run key, immutable thread and turn IDs, and an approved model and reasoning pair. The same connector and run key can send bounded heartbeats and events, then call bombyx_ai_ops_session_result_submit with a unique idempotency key. Completion requires passing checks and evidence. Exact result replay returns the recorded final state. These calls update the canonical Bombyx work item, AgentRun, session, and event ledger without claiming a manager lease.

Common Mistakes

Putting the raw token in a repo config file.
Calling MCP when a plain REST call would be easier.
Forgetting to restart the client after adding a new MCP server.
Giving a disposable worker ai_operations_manage when it only needs read and work capabilities.
Submitting artifact bodies instead of stable provider references and checksums.
Reusing a run key across independent worker processes.
Treating a discovered project as active. Inventory sync always imports dormant projects.
Sending local workspace paths, terminal output, or full Codex transcripts as session events.
Assuming a session heartbeat is durable project state. MySQL work, runs, events, and briefs remain authoritative.
Reusing a review idempotency key with different content, or sending changes_requested without exact correction instructions and acceptance criteria.
Treating broad production or external permission as standing authority. Use an exact standing-action identifier and durable policy reference.
Confirming a model profile before the bound host reports a matching model catalog and supported reasoning effort.
Assuming every organization has the same Brain Wiki pages or reusing stale page hashes.
Treating a Brain Wiki proposal as an approved or published change.