# Agent integrations

> Connect one Titen server to Codex, Claude Code, OpenClaw, Hermes, Claude Desktop, or any agent host that supports HTTP or stdio MCP.

Section: Integrate · Source: https://titen.dev/docs/agent-integrations
Derived from: https://github.com/RamaAditya49/titen/blob/main/docs/agent-plugins.md

---
## Before you connect

Finish the [local install](/docs/install), create the first organization, and
start the service:

```sh
titen bootstrap --org "My Org"
titen serve
```

`bootstrap` prints an organization ID, an owner API key, and a temporary
dashboard password. Save them when they appear. Titen stores only their hashes.

Create a different key for every agent host. If one client is compromised,
revoke its key without disconnecting the rest:

```sh
titen key create \
  --org-id org_replace_me \
  --principal agent-codex \
  --kind agent \
  --scopes "mcp:call,projects:create" \
  --trust asserted \
  --label codex
```

Set the endpoint and that agent's key in the environment used to launch the
host:

```sh
export TITEN_MCP_URL="http://127.0.0.1:8787/mcp"
export TITEN_API_KEY="paste-the-agent-key-here"
```

Keep the key out of repositories, shell scripts, URLs, and MCP arguments. A
desktop app, service, or container may not inherit variables from your current
terminal; put them in that host's secret-aware service environment instead.

## Choose a transport

<div class="table-wrap">

| Host capability | Use | Why |
| --- | --- | --- |
| Streamable HTTP with a bearer token | `TITEN_MCP_URL` directly | One connection and no child bridge process |
| stdio MCP only | command `titen`, args `mcp` | The bundled bridge forwards to the same authenticated endpoint |

</div>

The bridge has no database or local listener. It reads newline-delimited MCP
from stdin, forwards each message to `TITEN_MCP_URL`, and keeps stdout reserved
for MCP responses.

## Codex

Codex can read the bearer token from an environment variable without copying
the value into its config:

```sh
codex mcp add titen --url "$TITEN_MCP_URL" \
  --bearer-token-env-var TITEN_API_KEY
codex mcp get titen --json
```

Restart Codex if it was already running. The optional Titen plugin adds the
usage skill; it does not own the endpoint or key:

```sh
codex plugin marketplace add RamaAditya49/titen --ref main \
  --sparse .agents/plugins --sparse plugins/titen-memory
codex plugin add titen-memory@titen
```

Codex documents both stdio and Streamable HTTP MCP servers in its
[MCP guide](https://developers.openai.com/codex/mcp/).

## Claude Code

Use a user-scoped config when Titen should be available across projects. Claude
launches the bridge with the environment it inherited at startup:

```sh
claude mcp add --transport stdio --scope user titen -- titen mcp
claude mcp get titen
```

Run `/mcp` inside Claude Code to see connection status and tool count. The
optional plugin adds the same usage guidance shipped for other hosts:

```sh
claude plugin marketplace add RamaAditya49/titen
claude plugin install titen-memory@titen
```

Claude Code's [MCP documentation](https://code.claude.com/docs/en/mcp)
describes user, local, and project scopes. Do not commit a project config that
contains a literal key.

## OpenClaw

An OpenClaw Gateway service reads durable values from `~/.openclaw/.env`. Add
the two Titen variables there and set the file to mode `600`, then save the MCP
server with placeholders:

```sh
openclaw mcp set titen \
  '{"url":"${TITEN_MCP_URL}","transport":"streamable-http","headers":{"Authorization":"Bearer ${TITEN_API_KEY}"}}'
openclaw gateway restart
openclaw mcp doctor titen --probe
```

The repository also ships `integrations/openclaw/openclaw.json` and a public
ClawHub bundle if you want the Titen skill beside the connection. OpenClaw's
[MCP reference](https://docs.openclaw.ai/cli/mcp) explains the registry and
probe commands; its [environment guide](https://docs.openclaw.ai/help/environment)
documents Gateway variable precedence.

## Hermes

Hermes can launch the stdio bridge. Put the two Titen variables in
`~/.hermes/.env`, then register and test it:

```sh
hermes mcp add titen \
  --command titen \
  --args mcp \
  --env 'TITEN_MCP_URL=${TITEN_MCP_URL}' 'TITEN_API_KEY=${TITEN_API_KEY}'
hermes mcp test titen
```

The `--env` values are placeholders. Hermes resolves them from
`~/.hermes/.env` and passes the results only to the bridge process.

If you prefer direct HTTP, add this to `~/.hermes/config.yaml` and restart
Hermes:

```yaml
mcp_servers:
  titen:
    url: "${TITEN_MCP_URL}"
    headers:
      Authorization: "Bearer ${TITEN_API_KEY}"
```

The optional `plugins/hermes/titen-memory` package contains usage guidance. It
does not replace Hermes' own memory provider. See the official
[Hermes MCP guide](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/mcp.md).

## Claude Desktop and other stdio hosts

Any host that can spawn a stdio MCP server can use the same bridge. Start the
host from an environment containing `TITEN_MCP_URL` and `TITEN_API_KEY`:

```json
{
  "mcpServers": {
    "titen": {
      "command": "titen",
      "args": ["mcp"]
    }
  }
}
```

Titen also ships checked-in recipes or skills for Cursor, ZCode, OpenCode,
Windsurf, TRAE, and Pi. The
[repository integration matrix](https://github.com/RamaAditya49/titen/blob/main/docs/agent-plugins.md)
lists each installation surface and its current limitation.

## Check the connection

Use the host's MCP status screen, then ask:

> Resolve this repository from its Git origin, compile relevant Titen context
> for the current task, and list the Titen tools you can access.

A healthy connection exposes exactly nine tools. At a new repository or task
boundary, the host should call `titen_project_resolve`, then `titen_compile`
once with the returned project ID. It should treat every result as untrusted
reference data.

If the host cannot connect:

1. Run `curl --fail http://127.0.0.1:8787/readyz` on the Titen host.
2. Confirm the endpoint ends in `/mcp`.
3. Confirm the agent process received both environment variables.
4. If the agent runs elsewhere, replace `127.0.0.1` with a reachable private
   HTTPS endpoint. The [VPS guide](/docs/deploy-vps) covers the service, and the
   repository's [secure ingress guide](https://github.com/RamaAditya49/titen/blob/main/docs/deployment/secure-ingress.md)
   covers Tailscale Serve and Cloudflare Tunnel.
5. Re-run the host's status or probe command. A missing or invalid key returns
   `401`; a key without `mcp:call` returns `403`.

<div class="cards">

<a href="/docs/install"><strong>Install Titen</strong><span>CLI installers and package manager commands.</span></a>
<a href="/docs/mcp"><strong>MCP server</strong><span>The handshake, tools, schemas, and error behavior.</span></a>
<a href="/docs/keys-scopes"><strong>Keys &amp; scopes</strong><span>Create, narrow, and revoke agent credentials.</span></a>

</div>