Agent Host MCP

Turn your agent on the host into an MCP server.

Agent Host MCP lets your assistant work with the development environment on your Linux machine. Read project files, execute Python or shell commands, ask a remote Codex agent to carry out a task, and reuse knowledge from past sessions—all through one MCP connection.

Use it when your code lives on a remote host and you want your assistant to inspect that environment directly instead of copying files and terminal output into a conversation.

What you can do

• Understand a project: read contributor guidance, inspect files, and find saved Codex sessions.
• Get work done: run notebook-style Python cells or shell scripts, or delegate a task to Codex in a new or existing session.
• Keep useful context: build topic knowledge from sessions, then browse it in OpenWiki or search it from your assistant.
• Manage the host workflow: transfer files, label sessions, and inspect recorded token usage.

Quick start

1. Start Agent Host MCP on your host

You need a Linux host with Python 3.11+. For knowledge browsing and retrieval, also install Node.js 22.22.0+ and npm. Run the server as the account whose Codex sessions you want to use, with that account’s existing Codex login. Set CODEX_HOME if its configuration lives outside ~/.codex.

Install with uv:

uv tool install agent-host-mcp

Or install with pip in your Python environment:

pip install agent-host-mcp

Start the server:

agent-host-mcp --host 0.0.0.0 --port 7081 --api_key YOUR_MCP_TOKEN

Replace YOUR_MCP_TOKEN with a long, random secret and use the same value in your client. This key protects the MCP server; it is not an OpenAI API key. Codex uses its own existing login.

Use a configuration file instead

Save these values in config.toml:

host = "0.0.0.0"
port = 7081
api_key = "YOUR_MCP_TOKEN"

Keep the file private, then start the server:

chmod 600 config.toml
agent-host-mcp -f config.toml

JSON files with the same three fields are also supported. CLI flags override file settings, so you can change the port without editing the file:

agent-host-mcp -f config.toml --port 7082

--api-key is an alias for --api_key; --config is an alias for -f. Without explicit settings, the host is 127.0.0.1 and the port is 7081. If no API key is supplied by flag or file, the server uses MCP_TOKEN from the environment, then .env in its working directory.

The pinned OpenWiki dependency is installed automatically on first knowledge access and reused afterward. That first request needs npm registry access and may take longer; no extra setup command is required.

2. Add it to your Codex client

On the machine where you use Codex, set MCP_TOKEN to your server’s token. For example, in Bash you can enter it without placing its value in shell history:

read -rsp 'Agent Host MCP token: ' MCP_TOKEN
export MCP_TOKEN
printf '\n'

Register the server, replacing https://YOUR_HOST with your server’s HTTPS URL:

codex mcp add remotecodex \
  --url https://YOUR_HOST/mcp \
  --bearer-token-env-var MCP_TOKEN

Start your Codex client from an environment where MCP_TOKEN is available. Other MCP clients can use Streamable HTTP at /mcp with Authorization: Bearer <MCP_TOKEN>.

3. Ask your assistant to use it

Try requests such as:

Use remotecodex to read AGENTS.md in my project directory and summarize its guidance.

Run a Python cell that calculates 6 * 7 on the remote host.

Start a new Codex session in my project and ask it to investigate the failing tests.

Search my saved knowledge for deployment hints.

Replace “my project directory” with the actual host path. The client discovers available tools and their parameters through tools/list.

Choose the right execution tool

Task	Tool	What to expect
Run code directly	execute(string, path="~")	A persistent Python namespace per directory. Variables, imports and functions carry over between cells.
Run a shell script	execute with a cell beginning with ! or %	The whole remaining cell runs through /bin/sh in the chosen directory.
Delegate work to Codex	run(path, prompt, session_id=None)	Omit the ID for a new saved session; supply one to resume that exact session.

execute defaults to the server account’s home directory. run requires an existing working directory. Use create_path to create an absolute directory and its missing parents first.

execute uses the server’s installed Python packages and normal account permissions; it is not a security sandbox. Python variables last until the runtime or server restarts. Shell environment/directory changes do not carry over to later cells. run uses your saved Codex login and configured defaults for new sessions. A saved session must be closed in its current Codex client before resuming it here.

Collect a long-running result

run, execute, build_knowledge, and delete_session return an action_id immediately. Save it, then repeat the same tool and original arguments with that ID until its status becomes completed, failed, or interrupted.

For example, start a cell:

{"string":"6 * 7"}

Then call execute again with the returned ID:

{"string":"6 * 7","action_id":"returned-action-id","wait_seconds":20}

Omitting the ID starts new work. Reconnecting never reruns the original task. Keep an omitted path or session_id omitted when reconnecting. Inspect the nested result.status too: a completed action may contain a failed cell or turn.

A gateway timeout or disconnected client leaves the job running. Each reconnect waits at most 20 seconds. SSE carries progress and the final result, rather than live stdout or model tokens. Server shutdown interrupts active jobs; they are not automatically rerun. Completed results are retained for up to 24 hours, subject to a 256-action capacity.

Build and use your knowledge

Ask your assistant to call list_models, choose a supported model and depth, then call build_knowledge. Supply session_id to target one session, or omit it for an incremental batch. Unchanged, verified context is reused.

Browse the results at /knowledge and sign in with your MCP token. The OpenWiki page and wiki_list_pages, wiki_search, and wiki_read tools use the same saved knowledge. Viewing or searching it does not call a model. Browser visualization needs access to OpenWiki’s pinned external library/font CDNs.

While the server runs, it also checks for new or changed session context every 30 minutes. When idle, it runs a daily maintenance pass that still skips unchanged context. Builds use your Codex login and can make model calls.

Session retirement: knowledge builds may delete sessions whose working directories have been removed, after saving and verifying their knowledge. Sessions with existing working directories are preserved by automatic builds. delete_session explicitly deletes a selected session, including one whose working directory exists, only after its current knowledge is verified. Active or changed sessions, and sessions with remaining descendants, are kept.

Available tools

The server exposes thirteen tools. See the detailed reference for schemas, limits, outputs and failure handling.

Tool	Use it to
list_sessions	Find saved session IDs, models, depths, working directories and descriptions.
update_session	Set a client-managed description; blank text clears it.
list_models	Discover supported models and reasoning depths.
create_path	Create an absolute host directory and missing parents.
execute	Execute Python cells or prefixed shell scripts.
run	Start or resume a Codex session and submit a prompt.
build_knowledge	Extract reusable knowledge from changed or selected sessions; may retire missing-directory sessions.
delete_session	Delete a session only after its current knowledge is saved and verified.
token_count	Inspect recorded host/session usage and cache-hit ratios; retired usage appears in others.
get_upload_skill	Get instructions for authenticated HTTP file uploads.
wiki_list_pages	Browse knowledge topic pages with pagination.
wiki_search	Find relevant knowledge sections.
wiki_read	Read selected sections and their source provenance.

To transfer a local file, read get_upload_skill first. Uploads use a separate HTTP POST /upload with the same Bearer token, the actual file bytes, and a client-selected absolute destination directory. Missing parents are created; existing files are never overwritten. The file limit is 100 MiB. Native MCP auth does not automatically expose the credential to an agent’s separate HTTP client.

Token usage is recorded session usage, not an exact billing report. Cached and reasoning counters are subsets, and cache_hit_ratio is cached input divided by input; unknown coverage is reported.

Access and upgrades

The landing page at / is public. MCP calls, uploads and knowledge content require authentication. Signing in to the knowledge browser does not authorize MCP calls or uploads. Connect only clients you trust with the host account’s access.

Credential precedence is CLI --api_key, configuration api_key, exported MCP_TOKEN, then .env. Restart the server after changing its settings.

Keep your .env, Codex login and saved sessions when upgrading. Extracted knowledge is saved under ~/.agent-mcp/knowledge; preserve it and the other Agent Host MCP data described in the backup reference. Stop the previous service before starting its replacement on the same port, then refresh your client’s MCP connection to discover updated tools.

Check your setup

Check the installed version:

agent-host-mcp --version

Open the host’s / page, or ask your connected assistant to call list_models and list_sessions. These discovery tools do not submit model turns or delete sessions. Open /knowledge to sign in and browse saved knowledge.

Symptom	What to check
Unauthorized or startup token error	Match the server’s token and the client’s MCP_TOKEN environment variable.
Port 7081 is already in use	Stop the intended previous process yourself, or choose another --port.
Session has an active writer	Close its owning Codex session normally before resuming it, or omit the ID to create a separate session.
OpenWiki unavailable	Check Node.js/npm, npm registry access on first use, and browser CDN access.
Client still shows old tools	Refresh/reconnect the client after restarting the updated server; a new conversation alone may not refresh its cache.
Public gateway cannot be reached	Check gateway routing and any IP allowlist separately from the local server.

For detailed usage, limits and troubleshooting, see REFERENCE.md.