Codex MCP

Bayesilisk includes a local stdio MCP server for Codex-style connector workflows. It is designed to help Codex interview the user, establish connector provenance, generate a connector prompt packet, plan scenarios, verify connector outputs, and create fix briefs from verified findings only.

The MCP server is local-first:

  • it does not connect to production systems;

  • it does not mutate issue trackers;

  • it does not execute arbitrary app commands;

  • it does not let an LLM write observed statuses, pass/fail results, or issue readiness.

By default, the MCP process writes only framed MCP JSON-RPC messages on stdout and stays quiet on stderr. Set BAYESILISK_MCP_BANNER=1 for manual runs if you want the ASCII startup banner.

Install From GitHub

Until Bayesilisk is published to PyPI, install it from GitHub.

For normal use, install directly from the repository:

python3 -m pip install 'git+https://github.com/sashakolpakov/bayesilisk.git'
bayesilisk-mcp

For development, clone and install editable:

git clone https://github.com/sashakolpakov/bayesilisk.git
cd bayesilisk
python3 -m pip install -e .
bayesilisk-mcp

From an existing Bayesilisk checkout, run:

python3 -m pip install -e .
bayesilisk-mcp

For development extras:

python3 -m pip install -e '.[dev]'

For browser probing:

python3 -m pip install -e '.[playwright]'
python3 -m playwright install chromium

After a package release is published to PyPI, the normal package install should be equivalent:

python3 -m pip install bayesilisk

Configure Codex

Codex MCP servers are configured under [mcp_servers.<id>] in Codex config. The OpenAI Codex configuration reference documents command, args, cwd, startup_timeout_sec, and tool_timeout_sec for MCP servers: https://developers.openai.com/codex/config-reference.

Preferred configuration after installing Bayesilisk:

[mcp_servers.bayesilisk]
command = "bayesilisk-mcp"
args = []
startup_timeout_sec = 60
tool_timeout_sec = 120

For a project-local config while working from another repo, use an explicit checkout path. An absolute Python path is safest if Codex does not inherit your interactive shell PATH.

[mcp_servers.bayesilisk]
command = "python3"
args = ["-m", "bayesilisk.mcp_server"]
cwd = "/absolute/path/to/bayesilisk"
startup_timeout_sec = 60
tool_timeout_sec = 120

If this config is not in the Bayesilisk checkout, prefer installing the package and using command = "bayesilisk-mcp" so no checkout path is needed.

Restart Codex after changing MCP configuration. In Codex, check the MCP tool list with the normal MCP status UI or command for your Codex client.

Start A Connector Session

In a target application repo, ask Codex:

Use Bayesilisk to build a connector for this repo. Start by interviewing me
about the connector need, then establish provenance, generate a connector prompt
packet, plan scenarios, and verify connector outputs.

The intended MCP tool flow is:

interview_connector_need
  -> establish_provenance
  -> connector_prompt_packet
  -> Codex writes connector code in the target app/test repo
  -> scenario_plan
  -> connector executes local fixtures
  -> verify_connector_outputs
  -> fix_packet

Bayesilisk provides the contract, scenario proposal layer, validation, and deterministic verification. Codex writes app-specific connector code and runs the target app’s local fixtures through ordinary repo tools.

MCP Tools

Verifier tools:

  • run: run a contextual report.

  • rank_context: return ranked failed probes from supplied context.

  • issue_payloads: return deduped issue payloads for ready failed findings.

  • propose_probes: expand connector-supplied proposal rules and action graphs into app-agnostic probe proposals.

Codex orchestration tools:

  • interview_connector_need: normalize the user request and return short follow-up questions.

  • establish_provenance: record caller-supplied repository, source, test, and execution-boundary facts.

  • connector_prompt_packet: emit the prompt/spec packet Codex should use to create an app-specific connector.

  • scenario_plan: build a bounded scenario plan from source context, proposal rules, and ABAG action graphs.

  • verify_connector_outputs: validate observed connector evidence and run deterministic Bayesilisk verification.

  • fix_packet: emit a repair brief from verified findings or issue payloads only.

The MCP tools accept the same runtime-control names as the CLI where relevant: enableEmbeddings, embeddingModel, enableScenarioProposer, scenarioProvider, scenarioModel, scenarioProposalLimit, scenarioBaseUrl, scenarioApiKeyEnv, attentionThreshold, attentionSelectionLimit, and ollamaBaseUrl.

Trust Rules

Codex may draft:

  • connector source context;

  • connector action mappings;

  • scenario plans;

  • connector code in the target app or test repo;

  • fix prose and app patches after verified output.

Codex must not:

  • edit Bayesilisk core for an app connector;

  • invent source evidence;

  • invent observedStatus;

  • set passed without executing the app;

  • set issueReadiness;

  • open issues or patch code from raw connector output alone.

Only connector execution against local fixtures may create observed facts. Only Bayesilisk deterministic verification may produce issue-ready findings.

Minimal Connector Loop

  1. Codex reads local app tests, route handlers, schemas, and fixture helpers.

  2. Codex writes source context with explicit expectedStatus, proposalRules, proposalGates, or connectorActionGraph.sequenceRules.

  3. Codex calls scenario_plan or propose_probes.

  4. The connector executes returned actions against local fixtures.

  5. The connector writes observed context with expectedStatus, observedStatus, passed, targetUrl, artifacts, network responses, and timestamps.

  6. Codex calls verify_connector_outputs.

  7. Codex creates issues or app patches only from Bayesilisk verified issue payloads or fix packets.