> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Threat model for @hitheo/mcp — what runs where, how the JSON-only sandbox protects you, and how to verify the supply chain.

`@hitheo/mcp` is intentionally a small, predictable piece of software. This page covers exactly what it does, what it doesn't do, and what you can do to harden the install further.

## Where the server runs

| Property         | Value                                      |
| ---------------- | ------------------------------------------ |
| Process owner    | The same user that launched the IDE        |
| Transport        | Stdio (no inbound network port)            |
| Outbound traffic | HTTPS only, to `https://www.hitheo.ai`     |
| Lifetime         | Per-workspace; the IDE spawns and kills it |
| Persistent state | None — the server is stateless across runs |

The server is a Node.js process running as your local user. There is no daemon, no shared socket, no inter-IDE coordination. If you close the workspace, the process exits.

Because the transport is stdio rather than HTTP, **nothing on your network can talk to it**. The only entity that can call tools is the IDE process that spawned it as a child. Outbound, it speaks TLS 1.2+ to the same Theo API that any SDK or curl call uses.

## Where the API key lives

```text theme={null}
shell environment → IDE process → @hitheo/mcp child process → outbound HTTPS
```

The key flow:

1. You export `THEO_API_KEY` in your shell (or persist it for GUI app launches).
2. The IDE reads the value and forwards it as an environment variable when it spawns `@hitheo/mcp`.
3. The server reads it once at startup and stores it in process memory.
4. Every outbound call signs `Authorization: Bearer theo_sk_...`.
5. The IDE's agent itself **never sees the key** — it only sees the tool outputs.

This means:

* The key is never written to disk by `@hitheo/mcp`. (Your shell config or the optional `~/.theo/credentials` file may persist it, but those are CLI artifacts, not MCP ones.)
* The key is not transmitted to the IDE vendor, the model provider, or any third party. It goes straight to `api.hitheo.ai`.
* The key is not embedded in the tool descriptions, schemas, or resource bodies the agent can read.

If you ever leak a key into a chat log, [rotate it immediately](/security/authentication#key-rotation).

## The JSON-only config sandbox

`@hitheo/mcp` reads `theo.config.json` from the current working directory at startup. It deliberately **does not** read `theo.config.js` or `theo.config.ts` by default.

The reason is the threat model: an IDE will happily launch the MCP server inside any project you open, including ones you cloned from the internet. If JS/TS config were loaded automatically, a malicious `theo.config.js` could `import()` arbitrary code the moment the workspace opens — full arbitrary-code-execution as your user, before you've read a single file.

JSON config covers every documented use case (`persona`, `skills`, `defaultMode`, `tools`, `temperature`, `metadata`) without that risk.

If you genuinely need JS/TS config in a directory you trust:

```bash theme={null}
export THEO_ALLOW_JS_CONFIG=1
```

The server then loads `theo.config.js` first, then `theo.config.ts`, with the same JSON fallback.

<Warning>
  Only set `THEO_ALLOW_JS_CONFIG=1` in directories you authored or trust. Treat it the same way you'd treat `--allow-scripts` — a knob you turn on per-project, not globally.
</Warning>

## Supply chain

Every official `@hitheo/*` tarball on npm — including `@hitheo/mcp` — ships with [signed npm provenance](/security/authentication#supply-chain-verifying-npm-packages) starting at version `0.1.4`. Each attestation links the tarball back to the exact public CI workflow + git commit that produced it.

Verify before installing or pinning a new version:

```bash theme={null}
npm audit signatures @hitheo/mcp
```

You can also inspect the attestation URL for a specific release:

```bash theme={null}
npm view @hitheo/mcp@latest dist.attestations
```

If the attestation check ever fails for an official Theo package, **do not install it**. Report the issue to `security@opencharts.com` (see [Disclosure Policy](/security/disclosure-policy)).

## Pinning a known-good version

`npx -y @hitheo/mcp` resolves the latest published release on each install. If you want to lock to a specific version in CI or a shared dev environment, pin it in your IDE config:

```json theme={null}
"args": ["-y", "@hitheo/mcp@0.2.2"]
```

This makes upgrades explicit. Re-run `theo init` (or hand-edit) to move to a new release.

## What the agent can and can't do

The 8 [tools](/mcp/tools) and 3 [resources](/mcp/resources) are the **entire** surface the IDE agent sees. The MCP server does not expose:

* Your file system
* Your shell
* Your local processes or environment variables
* Any Theo internals beyond the documented HTTP endpoints

Any code the agent ends up running locally (`theo_code` returns code, not a runtime) is something *the IDE* offers to execute. That decision sits with you and the IDE's own permission model — `@hitheo/mcp` itself is read-only with respect to your machine.

## Key rotation, scopes, and revocation

`@hitheo/mcp` inherits the full key model documented in [Authentication](/security/authentication):

* **Hashed at rest** — Theo only stores SHA-256 hashes of `theo_sk_*` keys.
* **Scoped permissions** — each key can be limited to specific capabilities (completions, skills, tools, connectors, billing). A key without the `completions` scope cannot run `theo_complete`; the tool will return a `403 missing_scope` error to the agent.
* **Per-key rate limits** — limits apply per key, so a runaway IDE agent can't starve your other integrations.
* **Instant revocation** — revoke from the [dashboard](https://api.hitheo.ai/dashboard/api-keys) and the MCP server stops working within seconds (the next call returns `401 key_revoked`).

When rotating:

1. Create the new key in the dashboard.
2. Update the environment / shell where your IDE launches.
3. Restart the IDE.
4. Confirm with `theo verify` from the same shell.
5. Revoke the old key.

The grace window during rotation means there is no downtime for the IDE between steps 1 and 5.

## Reporting vulnerabilities

Found a security issue in `@hitheo/mcp` or related infrastructure? See the [Disclosure Policy](/security/disclosure-policy). Email `security@opencharts.com` rather than filing a public GitHub issue.

## Related

* **[Authentication](/security/authentication)** — full key model, scopes, rotation.
* **[Data Privacy](/security/data-privacy)** — how Theo handles your prompts and artifacts.
* **[Disclosure Policy](/security/disclosure-policy)** — how to report a vulnerability.