# Connect an agent to TypeFuse

TypeFuse is where teams build, test, version and ship the AI decisions their software makes.
Claude Code, Codex and claude.ai can build, test and call Decisions for you: install the skill,
add the TypeFuse tools, then sign in in your browser when the agent asks.

## In one line

Installs the skill for Claude Code and Codex (whichever it finds; choose with `--claude` or
`--codex`) and adds the TypeFuse MCP server to each. Read it first at https://typefuse.dev/install.
Then run /mcp in Claude Code, choose typefuse and Authenticate (Codex: `codex mcp login typefuse`). With TYPEFUSE_TOKEN set, it adds the server with the token instead (see the last section).

```sh
curl -fsSL https://typefuse.dev/install | sh
```

## URLs

- The app: https://typefuse.dev
- The API: https://api.typefuse.dev (`GET https://api.typefuse.dev/v1/meta` lists every URL, no token needed)
- MCP: https://api.typefuse.dev/v1/mcp
- The skill: https://typefuse.dev/agents/typefuse/SKILL.md
- API reference: https://api.typefuse.dev/docs

## Claude Code

1. **Install TypeFuse.** This installs the skill, which teaches Claude Code how to build, test and call Decisions, and adds the TypeFuse tools.

   ```sh
   curl -fsSL https://typefuse.dev/install | sh
   ```

2. **Sign in.** In Claude Code, run /mcp, choose typefuse and then Authenticate. Your browser opens TypeFuse so you can confirm.

3. **Ask your agent.**

   ```text
   Use TypeFuse to build a Decision that judges <what you want decided>. Write three to five Examples, evaluate it, and tell me before you publish.
   ```

## Codex

1. **Install TypeFuse.** This installs the skill, which teaches Codex how to build, test and call Decisions, and adds the TypeFuse tools.

   ```sh
   curl -fsSL https://typefuse.dev/install | sh -s -- --codex
   ```

2. **Sign in.** Your browser opens TypeFuse so you can confirm.

   ```sh
   codex mcp login typefuse
   ```

3. **Ask your agent.**

   ```text
   Use TypeFuse to build a Decision that judges <what you want decided>. Write three to five Examples, evaluate it, and tell me before you publish.
   ```

## claude.ai

1. **Add TypeFuse as a connector.** In claude.ai, open Settings → Connectors, choose Add custom connector and paste this URL.

   ```sh
   https://api.typefuse.dev/v1/mcp
   ```

2. **Sign in.** Choose Connect. Your browser opens TypeFuse so you can confirm.

3. **Ask your agent.** Start a chat with the TypeFuse connector turned on.

   ```text
   Use TypeFuse to build a Decision that judges <what you want decided>. Write three to five Examples, evaluate it, and tell me before you publish.
   ```

## TypeFuse CLI

1. **Install the CLI.** Not published yet. Needs Node.js 20 or later.

   ```sh
   npm install -g @typefuse/cli
   ```

2. **Sign in.** Your browser opens TypeFuse so you can confirm. On a server without a browser, the CLI shows a code to enter at https://typefuse.dev/device.

   ```sh
   typefuse login
   ```

3. **Check who you are.**

   ```sh
   typefuse whoami
   ```

## For CI and automated agents

A job or an agent that runs without you can't sign in with a browser. It uses a personal access token instead: give it the least access the job needs (Read, Run or Full), keep it in the job's secrets, and revoke it when the job no longer needs it.

1. **Create an access token.** Never paste it into a conversation with an agent. Create one at https://typefuse.dev/app?to=access-tokens.

2. **Use it from the CLI or the SDK.** Set it in the job's environment. TYPEFUSE_TOKEN wins over a stored sign-in; typefuse login --token stores it instead.

   ```sh
   export TYPEFUSE_API=https://api.typefuse.dev
   export TYPEFUSE_TOKEN=tf_pat_…
   # or: typefuse login --token tf_pat_… --api https://api.typefuse.dev
   ```

3. **Or give an agent the TypeFuse tools with the token.** The MCP server takes the token as a bearer header, so no browser is needed. The install script does this for Claude Code when TYPEFUSE_TOKEN is set.

   ```sh
   claude mcp add --transport http --scope user typefuse https://api.typefuse.dev/v1/mcp --header "Authorization: Bearer $TYPEFUSE_TOKEN"
   codex mcp add typefuse --url https://api.typefuse.dev/v1/mcp --bearer-token-env-var TYPEFUSE_TOKEN
   ```

## Calling a Decision from your app

Every Decision is answered by TypeSafe, the AI model provider TypeFuse runs on. The three ways differ in whose TypeSafe key answers and who sends the request.

- **BYOK.** The default. Your app sends its own TypeSafe key with each call; TypeFuse uses it for that call and never stores it. SDK: createRuntime({ apiKey, typesafeKey }).
- **Relay.** For a key that must never leave your systems. TypeFuse prepares the request, your app sends it to TypeSafe and hands the response back. A little slower, no shadows, and the audit marks responses as reported by your app. SDK: add route: "relay".
- **Managed.** TypeFuse's own key answers and the usage is billed; Enterprise, by contract.

The skill has the details, including Relay over plain HTTP: https://typefuse.dev/agents/typefuse/SKILL.md