# Connect

How an agent reaches the Frepi Platform MCP server, and what the session remembers.

## OAuth vs API key

The claude.ai connector uses OAuth. Nothing is stored between calls: pass `project_id` on every call. OAuth writes without `project_id` fail with `PROJECT_ID_REQUIRED` now. OAuth reads without it still run against the token's home until 2026-10-09, then they fail the same way. `bi_help` stays project-optional after the deadline.

A `bipk_` API key is bound to one workspace. Calls that omit `project_id` use that bound project. `bi_use_project` re-binds an API key; on OAuth it only verifies and stores nothing.

Create a key with `POST /api/auth/api-keys` while signed in (`{name, project_id}`). The secret is shown once.

Prefer the claude.ai connector, or from a terminal:

```
claude mcp add --transport http frepi https://mcp.frepi.ai/mcp/ --header "Authorization: Bearer bipk_…"
```

## What persists

OAuth: nothing. The next call does not remember the previous `project_id`. API key: the bound workspace, until `bi_use_project` re-binds it or the key is revoked.

Every result that reached a project echoes `project`; project-resolution errors do not. The echo has `id`, `display_name`, and `partnership_id`. Check `display_name` before a write.

## The tool list is full

Every client sees the full tool list. Whether a call works is decided per call by role and by the project's feature flags, not by hiding tools from the list.

## Roles

Legacy rank vocabulary still used in the MCP instructions: frepi_admin > partner_admin > editor > viewer. BI list/preview/describe/get tools are viewer-safe. BI writes (save/create/add/update/remove) need editor or above. Marketing and Analysis Studio tools state their own bar on the tool.

## feature_disabled

`FEATURE_DISABLED` means that project does not have the feature. The marketing console message is:

«La funcionalidad 'marketing_console' no esta habilitada para esta alianza.»

Do not retry. Pick a project where the console is on, or ask an admin to enable it.

## Install the skill

Without installing anything, call `bi_help("skill")` on the HTTP MCP server. To install the playbook for Claude Code, Codex, or Cursor:

```
npx skills add https://developers.frepi.ai
```

The human page is https://developers.frepi.ai/skills/.