Metadata-Version: 2.5
Name: agent-host-mcp
Version: 0.1.0
Summary: Connect Codex sessions, remote execution, and project knowledge to MCP clients.
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.12
Requires-Dist: openai-codex>=0.167.0
Requires-Dist: python-dotenv<2,>=1
Requires-Dist: python-multipart<1,>=0.0.33
Description-Content-Type: text/markdown

# 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**, uv, make, Node.js **22.22.0 or newer**, and npm. Run the
server as the account whose Codex sessions you want to use, with that account’s
existing Codex login and configuration. Set `CODEX_HOME` if they live outside
`~/.codex`. A separate API key is not required by Agent Host MCP.

From a source checkout or an unpacked source release:

```sh
make build
```

Create a `.env` file in the directory from which you will start the server:

```dotenv
MCP_TOKEN=replace-with-a-long-random-secret
```

Replace the placeholder with a long, randomly generated token. Restrict access:

```sh
chmod 600 .env
```

Keep an existing `.env` when upgrading. Keep the token private and provide the
same value to your client.

Start the server:

```sh
make run HOST=0.0.0.0 PORT=7081
```

The CLI is **`agent-host-mcp`**. After building, you can also start it directly:

```sh
./build/agent-host-mcp --host 0.0.0.0 --port 7081
```

Use the source-release setup above for all features, including OpenWiki.
Installing the Python wheel alone does not set up the knowledge viewer.

### 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:

```bash
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:

```sh
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:

```json
{"string":"6 * 7"}
```

Then call `execute` again with the returned ID:

```json
{"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](REFERENCE.md)
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.

The server reads `.env` from its working directory; an exported `MCP_TOKEN`
overrides the file. Restart the server after changing its token.

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](REFERENCE.md#long-running-tool-actions-and-sse).
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

With the server running and curl installed:

```sh
make test PORT=7081
```

This checks the advertised tools, session/model discovery, token accounting and
wiki retrieval. It does not submit model turns or delete real sessions. It prints
session and model results, so keep that output private.

| 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 | Run `make build` from the source directory and check Node dependencies 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](REFERENCE.md).
