Skip to main content

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.

@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

PropertyValue
Process ownerThe same user that launched the IDE
TransportStdio (no inbound network port)
Outbound trafficHTTPS only, to https://www.hitheo.ai
LifetimePer-workspace; the IDE spawns and kills it
Persistent stateNone — 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

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.

​
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: 
export THEO_ALLOW_JS_CONFIG=1
The server then loads theo.config.js first, then theo.config.ts, with the same JSON fallback.
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.

​
Supply chain

Every official @hitheo/* tarball on npm — including @hitheo/mcp — ships with signed npm provenance 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: 
npm audit signatures @hitheo/mcp
You can also inspect the attestation URL for a specific release: 
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).

​
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: 
"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 and 3 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:
  • 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 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. Email security@opencharts.com rather than filing a public GitHub issue.