# Install the Ask Timo skill and MCP server

You are setting up **Ask Timo** — an MCP service that lets an agent ask Timo, a human
expert, a question. Asking is free while Ask Timo is in beta, and paid later. Before every
send the agent must state the exact question and get the user's explicit yes; on hosts with
native forms the connector also shows that text in a dialog and sends only on confirm, and
on hosts without them the agent's own asking is the whole of the consent.

Execute the steps for your environment below directly. Do not ask the user to run the
commands themselves. Never ask for, read, or configure payment keys or credentials —
sign-in happens in the user's own browser via a link the server returns.

Requires Node.js >= 20.

## Claude Code

Install the plugin — it provides the MCP server plus the `timo` skill, which carries
the guided workflow. This is the required path:

```sh
claude plugin marketplace add tre-dev/timo
claude plugin install timo@timo
```

Only if your environment blocks plugin marketplaces (e.g. managed enterprise
settings), fall back to the bare MCP server:

```sh
claude mcp add --scope user timo -- npx -y timo-mcp@latest
```

## Install for other agents

For every config file below: create it if it does not exist, and **merge** the
`timo` entry into the existing JSON — never overwrite or remove other servers.

### Codex

Install the plugin — it provides the MCP server plus the `timo` skill:

```sh
codex plugin marketplace add tre-dev/timo
codex plugin add timo@timo
```

Only if your environment blocks plugin marketplaces (for example through managed
enterprise settings), fall back to registering the MCP server and copying the skill:

```sh
codex mcp add timo -- npx -y timo-mcp@latest
rm -rf /tmp/timo-plugin
git clone --depth 1 https://github.com/tre-dev/timo /tmp/timo-plugin
mkdir -p ~/.codex/skills
rm -rf ~/.codex/skills/timo
cp -R /tmp/timo-plugin/plugins/timo/skills/timo ~/.codex/skills/timo
rm -rf /tmp/timo-plugin
```

(The `rm -rf` lines make this safe to re-run: without them, `cp -R` onto an
existing `~/.codex/skills/timo` nests a second copy inside the first.)

### Gemini CLI

The plugin repository is also a Gemini extension, carrying the MCP server and the
`timo` skill:

```sh
gemini extensions install https://github.com/tre-dev/timo
```

### OpenCode — `~/.config/opencode/opencode.json`

Merge this `mcp` entry into the existing `~/.config/opencode/opencode.json`,
creating the file if absent:

```json
{
  "mcp": {
    "timo": { "type": "local", "command": ["npx", "-y", "timo-mcp@latest"], "enabled": true }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "timo": { "command": "npx", "args": ["-y", "timo-mcp@latest"] }
  }
}
```

### Cursor, GitHub Copilot, and all other agents

Cursor: the same `mcpServers` JSON as Windsurf, in `~/.cursor/mcp.json`.
VS Code (GitHub Copilot): in `.vscode/mcp.json`, under `"servers"` with
`"type": "stdio"`. Any other MCP-capable agent: register a stdio server with the
command `npx -y timo-mcp@latest`.

Hosts that only support remote MCP servers (ChatGPT, Claude.ai, Claude Desktop
connectors) skip the local install entirely: connect to
`https://mcp.timoreichert.com/mcp` over HTTP and sign in via OAuth when prompted.

## Verify

1. Confirm the `timo` server is connected and lists tools including `ask_timo`,
   `timo_balance`, and `sign_in_to_timo`.
2. Call `timo_balance`. It takes no arguments, sends nothing and costs nothing. If it
   returns `sign_in_required`, that is a successful setup: call `sign_in_to_timo` and
   show the user the returned message and link **exactly as returned — the complete URL,
   unmodified, on its own line**. Signing in sends nothing to Timo and charges nothing.

Once done, tell the user:

```
┌─ Ask Timo Setup Complete ────────────────────────────┐
│  ✓ MCP server   timo — npx -y timo-mcp@latest        │
│  ✓ Skill        timo                                 │
│                                                      │
│  Ask me to "ask Timo" whenever you want a human      │
│  expert's judgment. I'll show you the exact question │
│  and wait for your yes before sending. Asking is     │
│  free while Ask Timo is in beta.                     │
└──────────────────────────────────────────────────────┘
```

## Resources

- About the service: https://timoreichert.com/ask
- Plugin and skill source: https://github.com/tre-dev/timo