# OKR MCP Server — FlowyTeam

**Connect Claude, ChatGPT, or any MCP client to your OKRs, KPIs and tasks.**

FlowyTeam is a native [Model Context Protocol](https://modelcontextprotocol.io) server. Once
connected, an AI agent can read every objective and key result in your workspace, post
check-ins, move key-result progress, track KPIs and generate reports — in plain language,
without you opening a dashboard.

Unlike single-purpose OKR MCP servers, the same connection also exposes tasks, projects,
employees, attendance, leave, tickets, clients, leads and invoicing. **33 tools, one
connection.**

- 📘 Setup guide: <https://flowyteam.com/get/mcp-server>
- 📗 Full API reference: <https://flowyteam.com/get/mcp-docs>
- 🔌 OAuth connector docs: <https://flowyteam.com/mcp-docs>

> **What this repository is.** FlowyTeam's MCP server is hosted — it runs as part of the
> FlowyTeam platform, so there is nothing to install or self-host. This repository holds the
> connection configs, the tool reference and worked examples. If you are looking for a
> `npm install`-style local server, that is not how this one works: you point your client at
> a URL and authorize.

---

## Quick start

Pick the path that matches your client.

### Claude Desktop, Claude web, Claude mobile, or ChatGPT — OAuth

No API token to copy. Authorize once per app.

```
https://flowyteam.com/api/mcp/cloud/rpc
```

**Claude:** Settings → Connectors → Add custom connector → paste the URL → Log in →
Authorize. The consent screen shows exactly what the connector can access; nothing is shared
until you approve.

**ChatGPT:** Settings → Connectors → add the same URL and authorize.

Uses OAuth 2.0 with PKCE. Tools respect your existing FlowyTeam role and permissions.

### Claude Code (CLI) — Bearer token

Claude Code uses a different endpoint and a token instead of OAuth.

```bash
claude mcp add --transport http flowyteam \
  https://flowyteam.com/api/v2/mcp/rpc \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Get `YOUR_API_TOKEN` from FlowyTeam → **Settings → MCP & AI Integration**.

Or copy [`mcp.json.example`](./mcp.json.example) to `.mcp.json` in a project so the whole team
picks it up:

```json
{
  "mcpServers": {
    "flowyteam": {
      "transport": "http",
      "url": "https://flowyteam.com/api/v2/mcp/rpc",
      "headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
    }
  }
}
```

> ⚠️ The CLI endpoint (`/api/v2/mcp/rpc`) is **not** interchangeable with the OAuth connector
> endpoint (`/api/mcp/cloud/rpc`). Claude Desktop and ChatGPT cannot use the token endpoint;
> Claude Code cannot use the OAuth one. Use the one for your client.

### No account yet?

The public gateway exposes three onboarding tools with **no token required**, so an agent can
create and activate an account conversationally:

```bash
claude mcp add --transport http flowyteam https://flowyteam.com/api/mcp/gateway
```

Then ask your agent to *"register a FlowyTeam account for me"*. It calls `auth_register`,
you share the 6-digit code from the verification email, it calls `auth_verify_email`, and you
get an `api_token` back — reconfigure with that token and you are on the full tool set.

FlowyTeam has a free tier for up to 10 users; paid plans start at USD 3.33/user/month. MCP
access is included on every plan with no API add-on.

---

## Example prompts

These are the requests the OKR and KPI tools were built for:

```
Show me all Q3 objectives below 50% progress.
Check in on my key results and update this week's numbers.
Create an objective for the sales team with three key results.
Which KPIs are off target this month, and who owns them?
Summarise our OKR progress for the leadership review.
Align my objectives to the company goal for this cycle.
What's the current value of every indicator in the Revenue category?
Close out the Q3 performance cycle and open Q4.
```

Because the same connection reaches the rest of the workspace, you can also cross domains in
a single request:

```
Which team members own a key result that's off track and also have overdue tasks?
Draft a status update covering our OKR progress and open support tickets.
Log 2 hours against the Onboarding project and update the related key result.
```

---

## Tools

### OKR & KPI

| Tool | Methods | What it does |
|---|---|---|
| `objectives` | GET POST PUT DELETE | OKR objectives — list, create, update, delete. Filter by cycle, type (company/team/personal), status. |
| `key-result` | GET POST PUT DELETE | OKR key results — list, create, update, delete, update progress. Link to objectives. |
| `indicators` | GET POST PUT DELETE | KPI indicators — list, create, update, delete. Filter by category, employee. |
| `indicator-category` | GET POST PUT DELETE | KPI indicator categories/types. |
| `indicator-record` | GET POST DELETE | KPI actual values per period. Lookup by `indicator_id` + `period_key`. |
| `performance-cycle` | GET POST PUT DELETE | OKR performance cycles — list, create, update, delete. |

### Tasks & projects

| Tool | Methods | What it does |
|---|---|---|
| `tasks` | GET POST PUT DELETE | List, create, update, delete, mark complete. Filter by status, priority, project, assignee, due date. |
| `projects` | GET POST PUT DELETE | Projects plus milestones, members, categories and files. All lookups name-based. |
| `task-category` | GET POST PUT DELETE | Task categories. |
| `timelogs` | GET POST PUT DELETE | Time logs — start timer, stop/edit, delete. Filter by project, employee, date. |

### People & HR

| Tool | Methods | What it does |
|---|---|---|
| `employees` | GET POST PUT DELETE | List, show full profile, create, update, deactivate. Resolved by name or email. |
| `department` | GET POST PUT DELETE | Departments/teams, including member add/remove. |
| `designation` | GET POST PUT DELETE | Job designations/positions with member counts. |
| `attendance` | GET POST PUT | Clock-in, clock-out, list records. Filter by employee, date, month, year. |
| `leave` | GET POST PUT DELETE | Leave requests — list, create, approve, reject, cancel. |
| `leave-type` | GET POST PUT DELETE | Leave types (annual, sick…). Admin-only for writes. |
| `holiday` | GET POST PUT DELETE | Company holidays. Filter by year, upcoming/past. |
| `events` | GET POST PUT DELETE | Company events/calendar. |
| `notices` | GET POST PUT DELETE | Notice board. Filter by date range or audience. |

### Support

| Tool | Methods | What it does |
|---|---|---|
| `tickets` | GET POST PUT DELETE | Tickets and replies, stats, close/reopen. Name-based lookups. |
| `ticket-type` | GET POST PUT DELETE | Ticket types/classifications. |
| `ticket-channel` | GET POST PUT DELETE | Ticket channels (email, phone, chat…). |
| `ticket-agent` | GET | List ticket agents and their groups. |

### CRM & finance

| Tool | Methods | What it does |
|---|---|---|
| `clients` | GET POST PUT DELETE | Clients — list, create, update, delete. |
| `leads` | GET POST PUT DELETE | Sales leads. Filter by status, agent, date range. |
| `contracts` | GET POST PUT DELETE | Client contracts. |
| `invoices` | GET POST PUT DELETE | Client invoices — list, create, update status, delete. |
| `estimates` | GET POST PUT DELETE | Client estimates/quotes. |
| `expenses` | GET POST PUT DELETE | Expenses and claims, including approve/reject. |
| `expense-category` | GET POST PUT DELETE | Expense categories. Admin-only for writes. |

### Account (public gateway — no token)

| Tool | Methods | What it does |
|---|---|---|
| `auth_register` | POST | Create a new FlowyTeam company account. Sends a 6-digit verification code. |
| `auth_verify_email` | POST | Activate the account with the code and return the `api_token`. |
| `auth_login` | POST | Retrieve the `api_token` for an existing account. |

Full parameters, sample requests and error codes for every action:
<https://flowyteam.com/get/mcp-docs>

---

## Endpoints

| Endpoint | Auth | For |
|---|---|---|
| `https://flowyteam.com/api/mcp/cloud/rpc` | OAuth 2.0 + PKCE | Claude Desktop / web / mobile, ChatGPT |
| `https://flowyteam.com/api/v2/mcp/rpc` | `Authorization: Bearer <api_token>` | Claude Code (CLI), n8n, other HTTP MCP clients |
| `https://flowyteam.com/api/mcp/gateway` | none | `auth_register`, `auth_verify_email`, `auth_login` only |

## Permissions

Tools run as **you**. Every call is scoped to your workspace and to your existing FlowyTeam
role — an agent cannot read or change anything you could not read or change yourself in the
UI. Admins get full access; members get their own records plus whatever their role grants.

## Error codes

| Code | Meaning |
|---|---|
| `200` | Success |
| `401` | Unauthenticated — missing or invalid Bearer token |
| `403` | Forbidden — authenticated but lacks permission |
| `404` | Resource not found |
| `422` | Validation failed |
| `429` | Rate limited |

## Troubleshooting

**Claude Code shows no FlowyTeam tools.** Start a new session after adding the server —
tools are discovered at session start. Check `claude mcp list`.

**`401 Unauthenticated`.** The token is missing, expired or was pasted with the `Bearer `
prefix duplicated. Re-copy it from Settings → MCP & AI Integration.

**Claude Desktop can't connect to the CLI endpoint.** Expected — use the OAuth connector URL
(`/api/mcp/cloud/rpc`) instead. See the warning in [Quick start](#quick-start).

**`403 Forbidden` on a tool that should work.** Your FlowyTeam role lacks that permission, or
the module is disabled for your plan. Check with a workspace admin.

## Links

- Setup guide — <https://flowyteam.com/get/mcp-server>
- API reference — <https://flowyteam.com/get/mcp-docs>
- OAuth connector — <https://flowyteam.com/mcp-docs>
- Help centre — <https://resource.flowyteam.com/help-center/>
- FlowyTeam — <https://flowyteam.com>

## License

Documentation and examples in this repository are released under the [MIT License](./LICENSE).
The FlowyTeam platform itself is commercial software.