This MCP server provides workspace intelligence tools to help AI coding agents (like Codex) make safer, more informed edits by surfacing file fragility and co-change history from workspace.json.
workspace_get_file_context: Returns behavioral intelligence for a single file before editing — including whether it's historically fragile, the reason and evidence for its fragility, and which files have historically been edited alongside it (co-change partners).
workspace_get_cochange_partners: Lists files that historically change together with a given file, helping ensure related files aren't accidentally left out of a changeset.
workspace_list_fragile_files: Lists all files flagged as fragile in the workspace, sorted by risk score, to orient at the start of a task and identify high-risk areas.
workspace_assess_change: Evaluates a proposed changeset (list of file paths) against fragility and co-change history, returning a mechanical enforcement decision — deny (evidenced-fragile file missing required co-change partners), warn (partners missing or fragile but covered), annotate (fragility asserted without evidence), or none (no recorded history) — along with per-file assessments and explanatory messages.
Provides OpenAI Codex with behavioral history from workspace.json, including file fragility and co-change partners, to inform editing decisions and prevent incomplete changes.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@workspacejson/codex-mcp check context for src/routes/checkout.ts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Historical namespace
Development of the Codex integration is migrating to
workspacejson/integrations. The specification lives inworkspacejson/standard.This repository is retained because it is the current npm publication authority for
@workspacejson/codex-mcpand because it preserves the submitted OpenAI Build Week state. Publication has not yet cut over to theworkspacejsonorganization.
The OpenAI Build Week submission was finalized on July 21, 2026 (5:00 PM Pacific deadline).
For judging, the submitted project state is preserved at:
Git tag: codex-mcp-v0.1.9 (also available as build-week-2026-submission)
Commit: 7d42a61af78a383219c536cc49220f154a93a2bf
Commits made after the submission deadline are limited to repository maintenance, audit documentation, and branch/worktree reconciliation. They are not part of the work submitted for judging.
Commit | Date | Description |
| Jul 22 |
|
| Jul 22 |
|
| Jul 23 |
|
| Jul 23 |
|
Each of these commits touches only files under docs/audits/ — no source code, tests, dependencies, or packaging were modified after the deadline.
Installation and testing instructions for the submitted version remain available below. To check out the exact submitted state:
git checkout codex-mcp-v0.1.9Related MCP server: Scrooge
Task | Update the checkout route |
Recorded evidence | The route and its webhook partner share a repeated co-change history, including a rounding change and its later revert—not an import. |
An incomplete patch | The hook denies it, citing the specific evidence and the omitted partner |
Outcome | The incomplete patch does not land; Codex receives the evidence and must account for the recorded partner before retrying. |
npx @workspacejson/codex-mcp install --with-hookThat gives you MCP context plus the deterministic pre-edit hook — the enforcement shown in the 30-second demo above. It's idempotent, scoped to this repo's .codex/ directory, and never touches ~/.codex. Restart Codex, then run /mcp to confirm workspacejson is connected.
Add surfaces as you want them. Each flag is additive and asks for exactly the consent it needs — nothing is installed silently:
Command | Adds | Touches |
| MCP context (read tools) + optional GPT-5.6 reviewer | this repo's |
| + deterministic pre-edit hook | this repo's |
| + VS Code editor surface | your global VS Code (explicit consent) |
| the hook and the extension | both |
Uninstall mirrors that consent. npx @workspacejson/codex-mcp uninstall removes only what this repo owns — the MCP block, hook, and runtime — and leaves your global VS Code extension in place. To remove the editor extension too, ask for it explicitly: npx @workspacejson/codex-mcp uninstall --with-extension.
Add this to .codex/config.toml (project) or ~/.codex/config.toml (global):
[mcp_servers.workspacejson]
command = "npx"
args = ["-y", "@workspacejson/codex-mcp", "server"]
# Optional: point at a specific file or search root.
# env = { WORKSPACE_JSON_PATH = "/abs/path/.agents/workspace.json" }Without the hook you still get the read tools, but not deterministic enforcement.
# After `install --with-hook` (the installed path, works in any repo):
git diff --name-only | node .codex/workspacejson-codex-mcp/hooks/pre-edit-check.mjs --paths-stdin
# From a checkout of this repo (the source path):
git diff --name-only | node hooks/pre-edit-check.mjs --paths-stdinExit code 2 means a fragile change is missing a co-change partner; the reason prints with its evidence. Drop it into a GitHub Action to gate pull requests the same way the hook gates edits.
Let the installer handle the code CLI, idempotency, and the reload prompt for you:
npx @workspacejson/codex-mcp install --with-extensionThis installs the workspace-json.workspacejson-codex-decorations extension: Explorer decorations on fragile files, a current-change view, a synchronized status item, and saved review receipts. The decorations, current-change view, status item, and saved review receipts read local workspace data with no telemetry. Running a new advisory review is a separate explicit action that sends only the supplied diff to the configured provider.
The installer targets VS Code Stable only. If the code CLI isn't on your PATH it reports UNAVAILABLE with a one-line fix and leaves your MCP/hook install untouched — it never silently targets Insiders, Cursor, a remote, or a container. To aim it at a different editor's CLI deliberately, set WORKSPACEJSON_CODE_CLI (e.g. cursor) and rerun.
Building from a checkout of this repo? Produce the VSIX first, then install:
npm run build:extension
npx @workspacejson/codex-mcp install --with-extensionPrefer to install a pinned VSIX by hand (offline, or a release artifact)?
code --install-extension workspacejson-codex-decorations-<version>.vsixDemo and fixture repos may recommend the exact extension ID through .vscode/extensions.json; that's discovery only and never installs anything on its own.
The MCP server and hook consume .agents/workspace.json. The reference generator is agents-audit — a separate package in the same org:
npx agents-audit@0.4.3 generate .This writes .agents/workspace.json with repository topology and hygiene. Today, generated.fileIndex is empty and manual fragility/co-change evidence is not auto-generated — those remain human-authored (ASSERTED tier at minimum, OBSERVED when backed by evidence records). The generator does not guess risk signals; guessed churn has no evidence records, remains ASSERTED, and cannot block. See fixture/ for a worked example with manual evidence.
generate (above) writes repository topology only — no fragility or co-change evidence, so a freshly generated workspace.json has nothing to deny yet. To see the deny path itself, use this repo's fixture/, whose manual evidence is hand-authored for exactly this demo:
Open fixture/ in Codex. In Codex, ask it to edit src/routes/checkout.ts.
Watch the hook refuse the patch, citing the recorded evidence and the co-change partners the change left out.
Ask Codex to include both partners and retry — the edit proceeds.
No configuration beyond step 1 above. On your own repo, the same deny path activates once you've authored manual.fragileFiles / manual.coChangePatterns yourself — see docs/workspace-contract.md.
The judge-facing demo runs against workspace-json/billfold, a small public payments service. This is a separate proof path from this repository's local fixture/: Billfold uses the single recorded pairing shown on camera, src/routes/checkout.ts and src/webhooks/stripe.ts; the local walkthrough above uses src/auth/session.ts and src/lib/format.ts.
git clone https://github.com/workspace-json/billfold.git
cd billfold
git checkout 5e97f1dc9e6a41eb80d2d6eb80d5ef703cbe1cde # main as of 2026-07-20; no tag covers this pairing yet
npm install
npx @workspacejson/codex-mcp install --with-hookOpen billfold in Codex. Ask it to change the idempotency-key format in src/routes/checkout.ts.
The hook denies the patch, citing the recorded revert/incident and the omitted partner, src/webhooks/stripe.ts.
Ask Codex to include src/webhooks/stripe.ts and retry — the patch proceeds. That clears the recorded-partner check; it is not a correctness verdict on the change (see Current limitations).
This pins to the commit above because billfold's main is mutable and the two existing tags (fixture-v1, fixture-v2) predate this pairing — clone and stay on main instead if you want the current state.
MCP supplies context. A deterministic hook enforces evidenced omissions. An optional, direct read-only GPT-5.6 API review challenges a supplied completed diff and preserves its request/response receipt locally. The reviewer never controls the hook, and a PASS verdict is not a safety certification.
git diff | npx @workspacejson/codex-mcp review --diff-stdinRequires OPENAI_API_KEY (or OPENROUTER_API_KEY) in the environment. Without one, it reports UNAVAILABLE and deterministic enforcement is unaffected.
Full derivation rules for evidence tiers (ASSERTED/OBSERVED/VERIFIED), the hook's fail-open behavior, and the GPT-5.6 reviewer's scope live in docs/how-it-works.md.
Missing evidence never becomes a safety approval.
Malformed evidence never crashes the edit loop.
Reviewer output never controls deterministic enforcement.
Installation never overwrites unmanaged configuration.
Uninstall removes only owned artifacts.
The editor extension installs only with explicit --with-extension consent.
Every VERIFIED claim maps to a reproducible command.
Each is checkable, not asserted: run npm run verify from a clean clone to reproduce the gate this repository's own CI runs, or read the source citations in docs/operational-guarantees.md. See docs/failure-modes.md for the behavior behind each guarantee under missing, malformed, or unavailable input.
Local, no network: the MCP server, the deterministic hook, and the VS Code extension run over stdio and the local filesystem only. None of them upload repository contents or make network calls.
Network, by explicit action only: npx package installation contacts npm. The optional review command sends only the diff you explicitly supply to a configured API provider: OpenAI (OPENAI_API_KEY) or OpenRouter (OPENROUTER_API_KEY). When both keys exist, set WORKSPACEJSON_REVIEWER_PROVIDER to openai or openrouter; an explicit WORKSPACEJSON_REVIEWER_BASE_URL also selects OpenRouter. It uses store: false with OpenAI and preserves a local request/response receipt that identifies the provider and model. Do not supply diffs containing secrets.
Enforcement currently covers Codex apply_patch.
Other edit mechanisms may receive context without deterministic blocking.
Missing or malformed workspace.json fails open with an explicit unavailable warning.
Stale evidence is not treated as proof of current risk.
fragile:false means the file has no recorded fragility, not that it is verified safe.
Including a recorded partner's path clears the omission check; it confirms path coverage, not that the partner's content is correct or sufficient.
This does not replace tests, review, or repository instructions.
How it works — evidence tiers, hook enforcement, GPT-5.6 reviewer
Operational guarantees — the seven promises above, with source citations
Failure modes — behavior under missing, malformed, or unavailable input
Tools — full MCP tool reference (workspace_get_file_context, workspace_get_cochange_partners, workspace_list_fragile_files, workspace_assess_change)
The workspace.json contract — fields consumed and normalization
Verification — what's been verified and how
Build Week disclosure — what was authored in-window
Development — build, test, and smoke-suite commands
Clean-install audit · Fixture verification · billfold — the public repo behind the demo video
Apache-2.0
Evaluate a SET of file paths (a proposed change) against workspace.json fragility and co-change history, and return a mechanical enforcement decision.
Decision semantics (derived, never model-emitted):
"deny": an evidenced-fragile file is touched while its recorded co-change partners are absent from the changeset. Include the recorded co-change partners, or stop and review the exception with a human.
"warn": evidenced-fragile file touched (partners covered), or co-change partners missing on a non-evidenced file.
"annotate": fragility asserted without evidence. Context only.
"none": no recorded history. This is NOT a safety approval; this tool never certifies a change as safe.
Args:
paths (string[]): repo-relative or absolute paths in the proposed change (1-200).
Returns JSON: { "action": "deny" | "warn" | "annotate" | "none", "assessments": [{ "path", "fragile", "tier", "coChangePartners", "missingPartners", "action", "message" }], "workspaceVersion": string | null }
| Name | Required | Description | Default |
|---|---|---|---|
| paths | Yes | File paths in the proposed changeset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) are fully consistent with the description, which adds valuable context: the tool never certifies a change as safe, and it clarifies that 'none' is not a safety approval. The decision semantics are detailed, disclosing the mechanical enforcement logic. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-structured using bullet points for decision semantics and a JSON block for the return value. The purpose is front-loaded in the first sentence. While each sentence adds value, some redundancy exists (e.g., the return JSON is described both in text and in a code block). Still, it remains readable and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description provides a detailed return JSON structure with field descriptions, ensuring the agent understands what to expect. The tool's single parameter is fully covered by schema and description additions. The decision semantics are thoroughly explained, leaving no ambiguity about the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, describing the paths parameter with type, items, minLength, and maxItems. The description adds context beyond the schema, specifying 'repo-relative or absolute paths' and 'in the proposed change (1-200)', which helps the agent understand acceptable input. However, it does not explain how paths are resolved or validated further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Evaluate a SET of file paths…against workspace.json fragility and co-change history, and return a mechanical enforcement decision.' It uses a specific verb ('evaluate') and resource ('changeset'), distinguishing it from sibling tools like workspace_get_file_context (single file context) and workspace_list_fragile_files (listing fragile files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains decision semantics and when each applies (e.g., deny, warn, annotate, none). It implies usage for proposed changes but does not explicitly state when not to use or mention alternatives like the sibling tools. The context signals and sibling names provide implicit guidance, but the description could be more explicit about exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return behavioral intelligence about a single file from workspace.json BEFORE you edit it.
Combines two signals the current source tree cannot reveal on its own:
Fragility: whether this file is historically error-prone / high blast radius, with reason and evidence when available.
Co-change: which other files have historically been edited together with this one.
Call this before editing or creating a file. Treat a fragile result as a reason to make minimal, well-tested changes; treat co-change partners as candidates for related edits.
Args:
path (string): repo-relative or absolute file path.
Returns JSON: { "path": string, "fragile": boolean, "fragility": { "reason"?: string, "score"?: number, "evidence"?: string[] } | null, "coChangePartners": string[], "indexed": boolean, // whether the file appears in the workspace file index "workspaceVersion": string | null }
Returns fragile:false with empty partners when the file has no recorded history (this is a real answer, not an error).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The file path to look up. Absolute or repo-relative both work (matched on suffix). Example: 'src/db/client.ts'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing the two signal types (fragility and co-change) and explaining that 'fragile:false with empty partners' is a valid, non-error response. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and clear sections. Every sentence serves a purpose, and the length is appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description provides a detailed return JSON structure and explains edge cases (no history, file not indexed). It is complete for a read-only informational tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and already describes the path parameter well. The description does not add additional semantics beyond restating the parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'behavioral intelligence' about a single file, combining fragility and co-change signals. It distinguishes itself from siblings like workspace_assess_change and workspace_list_fragile_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this before editing or creating a file' and provides guidance on interpreting results (minimal changes for fragile, treat co-change partners as candidates). It lacks explicit exclusion of when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files flagged fragile in workspace.json, most fragile first (by score when present).
Use for orientation at the start of a task: it tells you which parts of the codebase carry the most historical risk.
Args:
limit (number, optional): max files to return (default 50, max 500).
Returns JSON: { "count": number, "total": number, "workspaceVersion": string | null, "framework": Record<string, string | number | boolean> | null, "files": [{ "path": string, "reason"?: string, "score"?: number }] }
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of fragile files to return (default 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses sorting order (most fragile first), default limit, and response format. Annotations already declare readOnlyHint and destructiveHint, so no contradiction. The description adds valuable behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and front-loaded with the main action. Including the full return JSON is helpful but adds length; still, every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description provides the complete return format and key behavioral details. Given the simple parameters and clear annotations, the description is sufficiently complete for accurate invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'limit', with default and maximum defined. The description restates these but adds no new semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists fragile files from workspace.json sorted by score. It distinguishes from sibling tools like workspace_assess_change, workspace_get_cochange_partners, and workspace_get_file_context by focusing on a specific subset of files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use for orientation at the start of a task: it tells you which parts of the codebase carry the most historical risk.' This tells when it should be used and its purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2workspace_get_cochange_partnersv0.1.0workspace_assess_changeworkspace_get_cochange_partnersworkspace_get_file_contextworkspace_list_fragile_filesEach tool has a distinct and clear purpose: get context for a single file, list fragile files, and assess a set of file changes. There is no ambiguity or overlap.
All tools follow a consistent 'workspace_verb_noun' pattern in snake_case, making them predictable and easy to understand.
Three tools is well-scoped for a specialized server focused on workspace.json code intelligence; each tool earns its place without being too few or too many.
The tool surface covers the core operations for the domain: inspecting individual file history, listing high-risk files, and validating changes against historical data. No obvious gaps for its intended read-only analysis purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Behavioral drift context (Behavioral Load Map, hot paths, release brief) for coding agents, per PR.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/workspace-json/codex-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
