# talon-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets your AI assistant set up [Talon Auth](https://talon.codes) in your project end-to-end — account creation, organization and application management, and framework-aware integration directly into your codebase.

## Requirements

- Node.js ≥ 22

## Setup

### Claude Desktop

Add the following to your `claude_desktop_config.json` (found at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "talon-mcp": {
      "command": "npx",
      "args": ["talon-mcp"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Claude Code

```bash
claude mcp add talon-mcp npx talon-mcp
```

### Other MCP clients

The server uses stdio transport. Point your client at:

```
command: npx talon-mcp
```

## Usage

Once connected, ask your AI assistant to add Talon Auth to your project:

> "Add Talon Auth to my app"

The assistant will work through the following steps automatically:

1. **Check status** — confirm whether you are already logged in
2. **Log in** — send a verification code to your email and confirm it
3. **List or create an organization** — organizations group your applications
4. **Create an application** — provide a name and the URLs your frontend runs on (e.g. `http://localhost:5173`)
5. **Investigate your codebase** — the assistant reads your project structure to identify your frontend framework (React, Vue, Svelte, …) and backend platform (Node.js, Bun, Cloudflare Workers, …)
6. **Integrate** — using the [Talon Auth documentation](https://talon.codes/docs), the assistant installs the right packages and writes idiomatic integration code for your specific stack

## Documentation

The integration step is driven by the Talon Auth docs at [talon.codes/docs](https://talon.codes/docs). The relevant sections are:

| Section | Covers |
|---------|--------|
| **Platforms** | Browser, Node.js, Bun, Deno, Cloudflare Workers |
| **Frameworks** | React, Vue, Svelte, Angular, Solid |
| **Backend frameworks** | Express, Fastify, Hono |

All integrations use the `<talon-login>` web component on the frontend and `createVerifier()` on the backend. Only your public application ID is needed — no secrets, no OAuth setup.

## Available tools

### Auth

| Tool | Description |
|------|-------------|
| `get_status` | Check whether you are currently logged in |
| `login_start` | Send a verification code to an email address |
| `login_verify` | Confirm the code to complete login |
| `logout` | Log out and clear stored credentials |

### Organizations

| Tool | Description |
|------|-------------|
| `list_organizations` | List all organizations for your account |
| `create_organization` | Create a new organization |

### Applications

| Tool | Description |
|------|-------------|
| `list_applications` | List applications in an organization |
| `create_application` | Create a new application with allowed referrer URLs |

### Integration docs

| Tool | Description |
|------|-------------|
| `get_docs` | Return the talon.codes documentation URL for a framework or platform so it can be fetched and read |

Supported targets: `react`, `vue`, `svelte`, `angular`, `solid`, `express`, `fastify`, `hono`, `browser`, `nodejs`, `bun`, `deno`, `cloudflare`.

## How authentication works

Talon Auth uses **device-based JWT tokens**. When you log in, the MCP server creates a device key stored in `.auth.json` (next to the installed package). Future sessions reuse this device automatically — you only need to verify your email once per machine.

Your application ID (`did:key:…`) is the public identifier embedded in all integration code. It is safe to commit to your repository.

## Resources

- [talon.codes](https://talon.codes) — dashboard, login page customisation, user management
- [talon.codes/docs](https://talon.codes/docs) — integration documentation
- [feathers.dev](https://feathers.dev) — feathers.dev platform docs
- [GitHub Issues](https://github.com/feathersdev/monorepo/issues)