# Connect an AI Agent

An AI agent — Claude, ChatGPT, or anything else that can call tools — can create, complete, and manage your TaskRatchet tasks on your behalf, right from a chat. Pick whichever path below matches your client.

## Using an MCP client

If your client speaks [MCP](https://modelcontextprotocol.io) (Model Context Protocol) — this now includes most current Claude surfaces, ChatGPT, and many other AI products — TaskRatchet runs a remote MCP server.

**For Claude Code**, run this once in your terminal (not inside a Claude Code session):

```sh
claude mcp add --transport http taskratchet https://api.taskratchet.com/mcp
```

**In another MCP client**, add a new connector pointing at:

```text
https://api.taskratchet.com/mcp
```

Either way, the first time you use the connection, your client sends you to TaskRatchet to log in and approve exactly which permissions the agent is requesting — you're authorizing that one agent, not handing out your personal API key. No need to visit your settings page or paste in a token. You'll see a screen like:

> **An application wants to access your TaskRatchet account**
> This will let it:
>
> - View your tasks
> - Mark your tasks complete or incomplete
> - ...

Approve it, and you're connected.

### Money-affecting actions go through a preview step

Anything that affects money — creating a task, editing one, marking one incomplete, giving up early ("uncle") — requires two separate calls: one that describes exactly what's about to happen, and a second one that actually does it. That split gives a well-behaved client a natural point to show you the preview and wait for your go-ahead before committing anything.

TaskRatchet can't force a client to actually pause there, though — a misbehaving one could make both calls back-to-back without asking you anything. Only connect agents/clients you trust to genuinely show you the preview.

### Managing access

See everything you've connected, and revoke access at any time, from [Connected Apps](https://app.taskratchet.com/settings/connected-apps) in your settings. Revoking stops future access immediately; a token already issued to the agent keeps working for up to 15 more minutes until it naturally expires.

## Using the Agent Skill

For a client that doesn't speak MCP, or if you'd rather use a personal API key than go through OAuth — install the `taskratchet-tasks` [Agent Skill](https://github.com/TaskRatchet/skills). It works with Claude and any other agent that supports the open Agent Skills format (Cursor, Codex, OpenCode, and more):

```sh
npx skills add TaskRatchet/skills --skill taskratchet-tasks
```

You'll need a TaskRatchet API key (**API Token** on your [account settings](https://app.taskratchet.com/settings) page) set as the `TASKRATCHET_API_KEY` environment variable. The skill relies on your agent's own consent prompts before it acts on your account.

## Which should I use?

- **Your client speaks MCP:** use MCP — OAuth handles login with a browser approval, and access is scoped to specific permissions and revocable per agent, without sharing your API key.
- **Your client doesn't support MCP, or you'd rather use a personal API key:** use the Agent Skill.
- **Claude Code specifically:** MCP is the simpler setup either way — one `claude mcp add` command plus a browser approval, versus generating and saving a personal API token for the Skill.

## Building an integration

Writing your own client instead of using an existing one? See the [OAuth Reference](/oauth) and [MCP Reference](/mcp).