Codex is most effective when it can use both kinds of context a team depends on:
the repository, files, terminal, and runtime evidence around the software;
the shared product decisions, research, launch plans, tables, and operating knowledge outside the repository.
Model Context Protocol (MCP) provides a standard bridge between Codex and a shared knowledge workspace. With a workspace-scoped connection, Codex can search, read, and—when authorized—update the same documents and tables the team reviews.
The short answer
To connect Codex to a shared knowledge workspace:
Create a dedicated workspace for the information Codex needs.
Generate a personal MCP connection or managed connector.
Add the remote MCP server through the Codex MCP settings available in your surface, or through the supported config.toml format.
Keep credentials outside the repository.
Start with search and read access.
Verify one harmless resource with a source link.
Add narrow write operations only after read behavior is trusted.
Require approval for public, destructive, or external actions.
In Dokki, a connection is scoped to one workspace. Connecting Codex to the Product workspace does not automatically grant access to Finance, HR, or another customer workspace.
Why connect Codex to shared knowledge?
Repository context is necessary but incomplete.
A product decision may live in a document. Customer evidence may live in a research table. The approved launch message may live in a GTM workspace. A migration exception may have been agreed in a meeting note.
Without a shared knowledge connection, teams usually:
paste context into every task;
duplicate briefs into repository files;
rely on stale summaries;
lose the source link;
ask Codex to infer business intent from code;
leave implementation outcomes trapped in a coding transcript.
With a governed connection, Codex can retrieve the current source and return reviewed outcomes to the same knowledge system.
What Codex can do with a connected workspace
Depending on the MCP server and permissions, Codex can:
search workspace knowledge by keyword or meaning;
read documents, tables, artifacts, or files;
retrieve a product brief before implementing a feature;
compare current code with approved acceptance criteria;
add source-backed research to an evidence table;
draft implementation notes or release documentation;
update a project or launch tracker;
create a linked handoff document;
preview a resource before publication;
keep operational documentation aligned with verified runtime behavior.
OpenAI's current Codex use cases include knowledge work and integrations such as turning feedback into actions, learning from dense source material, drafting PRDs from internal context, keeping documentation current, and running verified operations. A workspace connection makes those workflows durable and source-aware.
Choose the connection boundary first
Do not begin with the configuration command. Begin with the data boundary.
One workspace per trust domain
Useful boundaries include:
Product;
Engineering operations;
GTM and launches;
Customer research;
Public documentation;
Security review;
one client or one project.
A single company-wide connection is convenient but difficult to reason about. A narrow workspace makes access, search results, prompt-injection risk, and revocation easier to control.
Personal key or managed connector
Use a personal connection for:
one operator;
a proof of concept;
short-lived evaluation;
private local configuration.
Use a managed connector for:
a team workflow;
long-running automation;
a shared agent identity;
independent rotation and revocation;
access that should not depend on one employee.
Create separate connectors for different authority levels, such as:
product-research-readonly;
docs-draft-writer;
release-notes-writer;
public-publish-approver.
Understand the Codex configuration surfaces
Codex is available across several surfaces, and MCP setup can differ between versions and environments.
Possible configuration locations include:
the Codex app's settings or plugin interface;
a project-level .codex/config.toml in a trusted repository;
a user-level Codex config file;
a managed organization configuration;
a plugin that bundles an MCP server and related skills.
Use the setup instructions generated by the MCP service and the current Codex documentation for your installed surface.
Why this guide does not hard-code one command
Current Codex CLI versions can manage external MCP servers with codex mcp list, get, add, remove, login, and logout. The Codex app, CLI, and IDE extension use the same config.toml system, while trusted repositories can add project-scoped .codex/config.toml overrides.
Exact flags can still change across installed versions. Verify the active client with codex mcp add --help and treat the setup instructions generated by the MCP service as authoritative for its endpoint and authentication flow.
A copied command from another Codex version may fail even when MCP is supported through app settings or config.toml. Treat the current surface as authoritative.
Step 1: prepare the shared workspace
Before connecting Codex, organize the workspace so an agent can understand it.
Use clear folders
Example:
01 Product briefs
02 Customer evidence
03 Technical decisions
04 Launches
05 Operations
90 Standards
99 Archive
Use descriptive titles
“Authentication decision — July 2026” is easier to retrieve than “Notes 7.”
Mark canonical documents
Each important topic should have one current source and links to supporting evidence.
Add verification fields
Track:
owner;
status;
last verified date;
source URL;
applicable product version;
review or expiration date.
Archive stale material
Agents can retrieve obsolete content unless the workspace separates it clearly.
Step 2: create the MCP connection
In Dokki, open the target workspace's MCP connection settings.
Choose either:
an external client connection for the quick personal path;
a managed, named workspace connector for a team or agent.
Copy the server URL and authentication details exactly as provided. Do not rewrite the endpoint from memory.
Credential rules
Never commit a token to Git.
Do not paste credentials into a document or issue.
Avoid sharing screenshots that expose the full URL or header.
Use environment or secure configuration mechanisms supported by the Codex surface.
Name the credential owner and rotation date.
Revoke unused test credentials.
Step 3: add the server to Codex
Use the current Codex settings or supported config.toml syntax to define the remote MCP server.
For a Streamable HTTP server, the current CLI shape is:
codex mcp add dokki_product --url MCP_ENDPOINT
If the server uses OAuth, run codex mcp login dokki_product. Then verify the saved definition with codex mcp get dokki_product or inspect the /mcp status view in an interactive session.
The configuration generally needs:
a unique server name;
the MCP transport or remote URL;
the required authentication method;
optional timeouts or enablement settings.
Use a name that describes the boundary, such as dokki_product_readonly rather than knowledge.
Project versus user configuration
Use project configuration when:
the server definition belongs to one repository;
teammates should share non-secret configuration;
the workspace context is part of the project's standard workflow.
Use user configuration when:
the connection is personal;
the credential is used across repositories;
the endpoint or token should not be committed;
the workflow is experimental.
Keep the public definition separate from the private credential whenever the surface supports it.
Step 4: verify discovery
Restart or refresh Codex if the MCP catalog is loaded at session start.
Then ask Codex to inspect available MCP capabilities.
Confirm that it can identify:
the expected server name;
resource or tool descriptions;
search/read operations;
workspace scope;
which operations can write or publish.
If a newly added tool is missing, the current task may hold a stale MCP schema. Start a fresh task or reconnect before diagnosing the server implementation.
Step 5: run a read-only test
Create a harmless document named Codex MCP Connection Test.
Include:
a unique phrase;
one small decision section;
the expected workspace name;
no sensitive data.
Ask Codex:
Search the connected workspace for “Codex MCP Connection Test.” Return the document title, workspace, resource URL, and a three-bullet summary of the Decision section. Do not edit anything.
Verify the result
Did it search the intended workspace?
Did it return the correct resource?
Does the source URL open?
Does the summary match the actual text?
Did it avoid unrelated workspaces?
Did it perform no write actions?
A plausible summary without the correct resource link is not a successful connection test.
Step 6: test a controlled write
Only after read behavior passes, authorize one reversible write.
Example:
Create a document named Codex MCP Write Test in the Sandbox folder. Include the current date, the server name, and “safe to archive.” Return the resource URL. Do not modify any existing document.
Verify in the workspace UI:
correct workspace;
correct folder;
correct title and content;
visible activity or attribution;
no unrelated edits.
Then archive the test through the normal human workflow.
Step 7: connect repository work to workspace context
The highest-value workflow uses both sources without confusing their authority.
Repository is authoritative for
current code;
committed configuration;
tests;
migration files;
package versions;
deployment manifests;
runtime scripts.
Shared workspace is authoritative for
approved product intent;
customer research;
positioning;
decision logs;
launch state;
editorial standards;
cross-functional ownership.
Runtime is authoritative for
what is actually deployed;
production behavior;
logs and errors;
current database state;
live public rendering.
Codex should reconcile all three and state when they disagree.
A complete product implementation workflow
1. Retrieve the brief
Codex searches the connected Product workspace and reads the approved brief.
2. Inspect the repository
It locates the implementation area, current behavior, tests, and local conventions such as AGENTS.md.
3. Identify contradictions
It reports mismatches between the brief, code, and runtime evidence before changing anything.
4. Implement
Codex makes scoped repository changes and verifies them with relevant tests.
5. Update the shared artifact
It creates or updates an implementation note containing:
changed behavior;
files or pull request;
verification performed;
known limitations;
unresolved decisions;
deployment or migration notes.
6. Human review
Engineering reviews the code. Product reviews the behavior. The shared brief remains the cross-functional record.
A research-to-code workflow
A connected workspace is also useful before implementation.
Input
customer interview evidence;
competitor research;
product constraints;
existing technical decisions.
Codex work
retrieve and compare sources;
create a technical options matrix;
prototype the smallest useful approach;
test feasibility;
write findings to a reviewable document.
Output
A source-linked recommendation connected to actual repository evidence rather than a generic architecture suggestion.
A documentation maintenance workflow
Codex can keep shared documentation current, but only with an evidence hierarchy.
Read the target document and its last verification date.
Inspect current code and runtime behavior.
Identify statements that are stale or unsupported.
Update only affected sections.
Preserve or replace source links.
Set the new verification date.
Return the document URL and verification evidence.
Do not regenerate an entire document when a targeted correction is safer.
Permission model
Read and search
Appropriate for:
retrieving briefs;
finding decisions;
summarizing evidence;
comparing documentation with code.
Create-only or folder-scoped write
Appropriate for:
implementation notes;
research drafts;
test reports;
handoff documents.
Update specific resources
Appropriate for:
production trackers;
documentation maintenance;
status and verification fields.
Publish, share, delete, or message
Treat as elevated authority. Require explicit confirmation and separate credentials when possible.
MCP versus other Codex context mechanisms
AGENTS.md
Use AGENTS.md for durable repository instructions: commands, code conventions, verification requirements, and scope-specific rules.
Skills
Use a skill for a reusable workflow with instructions, references, scripts, or templates.
Plugins
Use a plugin when the workflow needs a bundled package of skills, MCP servers, tools, apps, hooks, or assets.
MCP server
Use MCP for live external data and actions, including private workspaces.
Thread context
Use the task conversation for one-off constraints and current decisions.
A good setup combines them:
AGENTS.md says how to work in the repository;
the workspace provides business and organizational truth;
a skill defines the repeatable workflow;
MCP supplies live access;
the current task provides the requested outcome.
Security checklist
The MCP credential is scoped to one workspace.
The server name makes the boundary obvious.
Secrets are outside Git and documents.
Read-only access is tested first.
Writes are limited to needed resources or folders.
Agent identity or connection ownership is visible.
Public, external, and destructive actions require confirmation.
Retrieved content is treated as data, not trusted instruction.
Tool descriptions distinguish read, update, send, publish, and delete.
Activity history or equivalent evidence is available.
Version recovery is tested.
The credential has an owner and rotation date.
Prompt-injection defense
A shared workspace can contain imported webpages, emails, files, or adversarial text.
Codex should follow this trust order:
system and managed policy;
explicit user request;
repository instructions in scope;
trusted workflow instructions;
retrieved workspace content as evidence.
Text inside a retrieved document should not silently grant tools, change the task, expose credentials, or trigger external actions.
Common problems
The MCP server does not appear
confirm the configuration belongs to the current Codex surface;
check project versus user config location;
refresh or restart the surface;
start a new task if schemas are cached;
verify the server is enabled and authentication is valid.
Known operations work but a newly added tool is missing
The current session may have an old tool catalog. Reconnect or open a fresh task before changing the server.
Search returns no result
verify the connection points to the expected workspace;
confirm the resource is not archived or private beyond the credential;
search the exact title;
inspect whether indexing has completed;
test direct read by resource ID if available.
Codex reads the wrong source
Require the resource title, workspace, URL, and last verified date in the answer. Narrow the workspace or folder boundary.
Codex can read but cannot write
Connectivity and write permission are separate. Check both the workspace role and connector capability.
Codex writes to the wrong folder
Name the workspace and destination explicitly. Require the returned resource URL and inspect it before allowing repeated runs.
The connection works locally but not for teammates
A user-level credential is private. Use a managed connector or shared non-secret project definition with per-user authentication.
A tool call repeatedly fails
Set a retry limit. Preserve the error, stop, and hand control to the user instead of generating a plausible success message.
Production rollout
Phase 1: individual read-only
one workspace;
one personal connection;
search and read only;
source-link verification.
Phase 2: controlled drafts
managed connector;
create in Sandbox or Drafts;
review every output;
test revocation and recovery.
Phase 3: workflow updates
allow table-row or section updates;
define ownership and statuses;
add a reusable skill;
monitor accepted edits and errors.
Phase 4: recurring operations
schedule verified maintenance tasks;
separate publish or external credentials;
audit permissions and stale sources;
measure end-to-end reviewed outcomes.
Metrics
Do not measure only tool-call count or generated text volume.
Frequently asked questions
Can Codex connect to an MCP server?
Yes. Codex supports MCP integrations, although setup surfaces and commands can vary by Codex version and environment. Use the current Codex settings or documented config.toml format.
Can Codex read a private knowledge workspace?
Yes, when an authorized MCP server exposes the workspace and the credential has permission. Keep the connection scoped to the smallest useful boundary.
Can Codex update shared documents and tables?
Yes, if the MCP server exposes write operations and the credential is authorized. Start with reversible, narrowly scoped writes.
Should MCP credentials be committed in config.toml?
Do not commit secrets. A project configuration may contain a non-secret server definition, while authentication should use the secure mechanism supported by the environment.
Is MCP better than copying a brief into the repository?
MCP is better when the brief is shared, changes outside code review, or must remain linked to other workspace resources. Repository documents remain useful for technical truth that belongs with the code.
Does Codex automatically trust workspace content?
It should not. Retrieved content can be stale, incorrect, or malicious and should be treated as evidence within the instruction hierarchy.
Can one connection access every Dokki workspace?
Dokki documents workspace-scoped MCP connections. A connection operates inside one workspace and does not automatically reach others.
What should Codex write back after implementation?
A concise implementation note with changed behavior, verification, code or pull-request link, limitations, unresolved decisions, and the resource URL.
Do I need a separate connector for each project?
Use separate connectors when projects have different owners, data boundaries, permissions, retention, or revocation needs.
What is the safest first Codex MCP workflow?
Search and summarize one harmless, uniquely named document with its resource URL and no write access.
Final checklist
The workspace boundary is explicit.
Canonical sources are identifiable.
A personal or managed connection was chosen deliberately.
The current Codex surface supports the configured method.
Secrets remain outside the repository.
Server discovery was verified.
A read-only test returned the correct resource URL.
A controlled write landed in the intended folder.
Repository, workspace, and runtime authority are separated.
Elevated actions require confirmation.
Revocation and version recovery were tested.
Workflow outcomes are written back with evidence.
Final recommendation
Connect Codex to one narrow knowledge workspace and prove read-only retrieval first. Then add reversible creation and targeted updates, keeping repository truth, organizational decisions, and runtime evidence distinct.
The goal is not to expose more context. It is to give Codex the smallest trusted path from shared intent to verified implementation and back to a reviewable team artifact.