# Bluefie: instructions for agents Bluefie is a business workspace: websites, CRM, marketing, products, people, learning and documents. This file says how an agent connects to it, what it may do, and how to read the answers. Updated: 2026-09-30 ## Where things are - MCP server: https://bluefie.com/api/mcp - MCP OAuth discovery: https://bluefie.com/.well-known/oauth-protected-resource/api/mcp - Projects REST API: https://bluefie.com/api/public/v1 - Booking API on hosted websites: https://sites.bluefie.com/api/public/v1 - OpenAPI 3.1 document for both REST APIs: https://bluefie.com/openapi.json - Developer docs: https://bluefie.com/developers - Claude plugin marketplace: https://bluefie.com/claude/marketplace.json - Skill pages: https://bluefie.com/skills - Site summary: https://bluefie.com/llms.txt ## Connect over MCP - Endpoint: https://bluefie.com/api/mcp - Transport: Streamable HTTP. - Authorization: OAuth 2.1 with PKCE. - Discovery: https://bluefie.com/.well-known/oauth-protected-resource/api/mcp - A request without a valid token answers 401 with a WWW-Authenticate header that names the discovery document. - A person signs in to Bluefie and approves the connection once, on Bluefie's own screen. - Without a workspace key the connection is read only: it can list, search and summarize, and it has no write tools. - Workspace keys: an owner or an admin issues one in Settings, then Connections: https://bluefie.com/dashboard/settings/connections - A workspace key names which modules it may read and which it may write. - A workspace key is bound to the workspace that issued it and acts only there. - A workspace key is registered for one agent host when it is issued. A key issued for one host does not connect from another. - Plain keys, for agents that cannot sign in: the same page issues a key beginning blf_agent_. Send it as Authorization: Bearer . There is no approval screen. It is shown once. - Keys are revoked from the same page. A revoked key stops working within seconds. - Listed by default: a small core set of read tools. - More reads: find them with search_tools and run them with execute_read_tool. - X-Toolsets header: comma-separated module names, for example X-Toolsets: customers,sites, lists those modules' read tools up front. An unknown name adds nothing. - Before promising an action, check the tools you have. A connection without a write tool cannot write. ## Approvals and parked actions - A result carrying awaiting_confirmation: is parked. It is waiting for a person on the review board: https://bluefie.com/dashboard/projects - A parked result is not a failure. The action was recorded, checked and queued for a person. - Never retry a parked call. A retry does not speed anything up and can park a second copy. - Do not look for another tool that gets the same outcome without the approval. - Tell the user the action is waiting for approval. Do not say it was sent or done. - A result carrying staged: true is a proposal with a before and after diff. Nothing has changed yet. - A person accepts a staged proposal on the review board. The accept is where the change happens. - publish_site, update_seo and post_job are staged. Never say a site is live, an advert is up or a page title changed because the call succeeded. - Every write tool accepts an optional idempotencyKey. - If a call failed in transit and you do not know whether it landed, retry with the same idempotencyKey. Bluefie performs nothing twice. - Use a new idempotencyKey for a genuinely new action. ## Rate limits ### MCP - 60 tool calls per workspace per minute. - Each workspace key has a daily call quota: 200 by default, up to 2000, set when the key is issued. - The daily quota resets at midnight UTC. - Workspace keys: every response carries RateLimit-Policy: "daily";q=;w=86400, "minute";q=60;w=60 - After a tool call it also carries RateLimit: "daily";r=;t= - Over the daily quota: Retry-After in seconds to midnight UTC. The result carries retryAfterSeconds and rateLimit with policy daily. - Over the minute limit: Retry-After and RateLimit: "minute";r=0;t=. The result carries retryAfterSeconds and rateLimit with policy minute. - Wait retryAfterSeconds before calling again. Do not retry sooner, and do not reword the request to get around the limit. - A connection without a workspace key gets no rate-limit headers. The 60 a minute limit still applies to it. - A paused connection answers 503 with Retry-After: 60. - Every other 503 from the MCP endpoint is an outage and carries Retry-After: 30. Wait that long, then try again. - With a workspace key, a tool call whose answer takes longer than 50 seconds answers 503 with Retry-After: 30. Try it again. For a write, send the same idempotencyKey. - A 400 whose error is Action needed is waiting on a person, not an outage: tell the user what the reason says. Never retry it unchanged. - A refusal can come from the daily quota, a workspace-wide pause or a revoked key. Tell the user which one the message points to, and send them to Settings, then Connections. Do not reword the request and try again. ### Projects REST API - 120 requests per minute per key, in a fixed window. - Every answer after the key is checked carries RateLimit-Policy: "key";q=120;w=60 and RateLimit: "key";r=;t=. - That includes every error after the key is checked: 400, 403, 404, 429, 500 and 503. A 401 carries neither, because that key was not counted. - Over the limit: 429 with Retry-After in seconds. - Projects not set up on the workspace yet: 503 with Retry-After: 3600. ### Booking API - 60 requests in a burst per caller address, refilling 1 per second. - 120 reads (availability and quote) per minute per site. - 30 booking requests per minute per site. - Over a limit: 429 with Retry-After in seconds. ## Projects REST API - Base URL: https://bluefie.com/api/public/v1 - Reference: https://bluefie.com/openapi.json and https://bluefie.com/developers - Keys: an owner or an admin mints one in Settings, then Integrations: https://bluefie.com/dashboard/settings?tab=integrations - A key is blf_live_ followed by 40 hex characters. It is shown once. - Send it on every request: Authorization: Bearer - Scopes: projects:read for every GET, projects:write for every POST and PATCH. - A key belongs to one workspace and never sees another. Private boards are not visible to a key. - Success: { "data": ..., "meta": { "nextCursor": ... } }. meta appears on lists only. - Failure: { "error": { "code": ..., "message": ... } }. - Error codes: unauthorized 401, forbidden 403, invalid_request 400, not_found 404, rate_limited 429, server_error 500, unavailable 503. - A missing, malformed, unknown or revoked key always answers the same 401. - Lists: limit from 1 to 100, 50 by default. Pass meta.nextCursor back as cursor. The last page has nextCursor null. - Request bodies are camelCase. Responses are snake_case. ## Booking API - Base URL: https://sites.bluefie.com/api/public/v1 - The same paths answer on every hosted site's own address (.sites.bluefie.com) and on its custom domain. - No key. Anonymous. - GET /availability?site=&date=YYYY-MM-DD: bookable times, by day. - POST /quote with { site, services: [{ name, quantity }] }: a price for services the site publishes. - POST /bookings with { site, name, email or phone, date, time, reason }: requests an appointment. The business confirms it. - POST /bookings requires an Idempotency-Key header: a stable id for this booking attempt. - A retry with the same Idempotency-Key and the same body answers the first result again with Idempotent-Replay: true, and books nothing more. - The same Idempotency-Key with a different body answers 422. - 409 means the time is taken. 503 means the booking API is not switched on for that site yet. - Failure: { "error": "" }, with issues on a 400 or available on a 422 from /quote. ## Read more - Connect Claude to a workspace: https://bluefie.com/skills/bluefie-setup - Install the Bluefie skills in Claude Code: /plugin marketplace add https://bluefie.com/claude/marketplace.json then /plugin install bluefie@bluefie - Every skill: https://bluefie.com/skills - API reference: https://bluefie.com/openapi.json - Contact: info@bluefie.com