# Connect an AI agent to FlowLakes over MCP

This page is the guide for pointing an AI client at a FlowLakes tenant over the [Model Context Protocol (MCP)][mcp]. It covers the hosted streamable HTTP endpoint and a scoped API token. Local stdio is development only (`mcp_server/CONNECTING.md`).

[mcp]: https://modelcontextprotocol.io

## 1. What you get

A connected agent works as one user, inside one tenant, inside one of four profiles: Read-only Analyst, Desk Assistant, Desk Lead, or Builder. Admin scopes are never grantable.

<!-- mcp-builder-hints:start -->
Check a table before you save it with `try_table`, then create it with `create_table`. Add a column with `create_field`.
Check a workflow with `try_workflow`, then create it with `create_workflow`.
Check a business rule with `try_business_rule`, then create it with `create_business_rule`.
<!-- mcp-builder-hints:end -->

There is no `plan_table`, `plan_workflow`, `add_field`, `test_workflow`, or `app_draft_*` tool. `plan_agent`, `plan_report`, and `plan_manifest_blueprint` remain.

## 2. Addresses

| Purpose | URL |
| --- | --- |
| App and REST API | `https://<tenant>.flowlakes.com` |
| MCP endpoint (streamable HTTP) | `https://<tenant>.flowlakes.com/mcp` (the longer `/mcp/mcp` reaches the same endpoint) |
| MCP discovery document | `https://<tenant>.flowlakes.com/.well-known/mcp.json` |
| Older SSE stream, kept for clients that need it | `https://<tenant>.flowlakes.com/mcp/sse` and `/mcp/messages` |

Do not use `https://mcp.<tenant>.flowlakes.com`. The certificate covers one label, and that host is not the MCP server.

## 3. Mint a token

Open **Admin, Access & Governance, Connected assistants** (`/admin/mcp-access`).

Expiry defaults to 90 days and cannot be more than 365 days out. The page shows the secret once. The connect command does not contain it.

```bash
export FLOWLAKES_API_KEY='the secret shown once'
claude mcp add --transport http flowlakes \
  https://<tenant>.flowlakes.com/mcp \
  --header "Authorization: Bearer $FLOWLAKES_API_KEY"
```

A request with no credential returns 401 and `WWW-Authenticate: Bearer realm="flowlakes"`.

Snippets for Cursor, VS Code and Claude Desktop: https://flowlakes.com/agents.

Call `get_current_user` first. It names the tenant, the acting user and the profile. Then `get_platform_capabilities`. A Builder token also lists `list_tables`.

## 4. Limits

60 calls a minute per token and 600 a minute per tenant are enforced in the server, on the API token. They are not a reverse-proxy setting. Hitting one of these two answers inside the reply itself, as `{"ok": false, "error_code": "rate_limited", "retry_after_seconds": N}`, plus a `Retry-After` header, because a 429 on the message POST would not reach an open streaming session.

429 is a different, coarser fence: the flood guard in front of the connection itself. A flood of the HTTP channel returns 429 with `Retry-After`. The bucket is the credential in the `Authorization` header, not the client IP.

*If this page and the running server disagree, the server wins.*