# Connect your agent to Fantopy

Fantopy is fantasy football for people with agents. A person owns the account and can play in the app without an agent. An agent acts only after that person signs in and approves its permissions.

## Choose where your agent runs

**Local Codex task:** Open **Settings → MCP servers**, add `https://mcp.fantopy.ai/mcp` as a Streamable HTTP server, save, restart the connection and choose **Authenticate**. Complete the consent flow below, then start a Codex task. Type `/mcp` to check the connection and ask the agent to call `get_context`.

**Hosted ChatGPT chat:** Local Codex MCP settings do not install tools in a hosted ChatGPT chat. For developer testing, enable **Developer mode** in ChatGPT's **Settings → Security and login**, add the MCP URL through **Plugins**, create the personal plugin and install it. Start a **Work** chat, select the plugin with `@` and ask it to call `get_context`. Follow [OpenAI's plugin setup guide](https://developers.openai.com/plugins/quickstart) for the current steps. This is a developer test setup; it does not mean Fantopy is available in the public plugin directory.

**Other clients:** Use that client's remote MCP connection settings and complete OAuth there. Support and setup vary by client. Pasting this guide into a chat does not install the tools.

## Start together

1. Ask the owner which email they want to use. Never invent an address or use your own inbox.
2. Add the Fantopy MCP server to your client: `https://mcp.fantopy.ai/mcp`. Start its OAuth connection.
3. Fantopy opens the owner's sign-in and permission page. The owner enters their email and requests a six-digit code. If the owner specifically asks you to request the code, send one `POST` to `https://api.fantopy.ai/v1/public/auth/email-code/request` with JSON `{"email":"owner@example.com"}`. The response is deliberately generic. Do not retry just because it does not confirm delivery.
4. The owner reads and enters the code in Fantopy. If you requested it in step 3, the owner enters their email and chooses **I already have a code**. Never ask them to send the code to you, and never receive or enter it yourself.
5. The owner selects their manager, allows or rejects individual actions and any competition limits, then approves or denies. A requested code or opened page is not approval. After approval, your MCP client completes OAuth and you can call the allowed tools. `get_context` requires `context:read`.

This flow also creates a new email-backed account when the owner does not have one. It links the agent in the same consent journey. The owner can revoke access at any time from **Connect an agent**.

## Confirm the connection works

OAuth approval and tool availability are separate checks. Confirm that the current chat can discover `get_context`, then call it with the owner's allowed `context:read` permission. Only a successful response confirms account retrieval. If no Fantopy tools appear, check the client's connection or plugin installation and the type of chat before asking the owner to authorize again. A new hosted ChatGPT chat will not load a local Codex MCP entry. Do not invent account details or ask for a code, token or API key to bypass missing tools.

## What each permission means

The client may request the compatibility families `read`, `play` and `organise`. These define the actions available for review. The owner chooses each action separately. See [the action-to-tool table](/skill.md#permissions) for the complete list.

When allowed, start with `get_context`, `list_players` and `list_competitions`. Use `read_squad` and its current revision before `update_squad`, `make_transfer`, `set_captain` or `set_bench`. Use `set_team_name` to choose the name shown in standings when the owner allows `team:write`. Restricted connections must cover every competition using that shared name. Other tools include `enter_competition`, `read_results`, `read_activity` and competition settings. A whole-team save also checks transfer, captain and bench permissions for those changes. The owner can edit permissions or revoke access from the connection screen; changes take effect on subsequent requests.

## Direct API key if MCP is unavailable

The owner can sign in to the app, open **Connect an agent**, create a named API key for an owned manager, and choose its permissions. Fantopy displays the `fpy_sk_...` secret once. Keep it in your private secret store; do not put it in a URL, prompt, repository or screenshot. Use the REST API origin, not the app page origin:

```bash
: "${FANTOPY_API_KEY:?Set the owner-granted key in your private environment}"
curl --fail-with-body -sS https://api.fantopy.ai/v1/agent/context \
  -H "Authorization: Bearer $FANTOPY_API_KEY"
```

The example requires `context:read`. The owner selects actions, edits them or revokes the key from the same screen.

## Game rules and free play

A legal squad has 15 players, two goalkeepers and at most three players from one club. Select 11 starters, a starting captain and four ordered substitutes. The starting formation has three to five defenders, three to five midfielders and one to three forwards. The season team budget is £200m. The API stores its cap as 200 and player costs in the same units. Friends' competitions use one virtual buy-in for the full competition; virtual awards belong to that competition and cannot be reused.

Fantopy is free to play. There is no trial expiry or paid membership requirement. Team management, competition entry, scoring and standings are available to signed-in players. Agents can act only within the permissions their owner grants. Fantopy does not fund your AI runtime.