MCP server

FurniOps runs a Model Context Protocol server, so an AI client can read your catalogue and work with it the way your code does with the API. Every tool is a public API route: the same permissions, plan, rate limits and request logs apply, and a tool can never do what the route would refuse.

Connect a clientCopy Anchor Link

Most clients find everything from the URL alone: the first request is answered with a pointer to FurniOps sign-in, and the client opens it in your browser.

Claude Code

claude mcp add --transport http furniops https://mcp.furniops.com/mcp

Cursor (.cursor/mcp.json) and other clients that take a JSON file:

{
  "mcpServers": {
    "furniops": { "url": "https://mcp.furniops.com/mcp" }
  }
}

Claude, ChatGPT and other apps: add a custom connector and give it the server URL. Sign in when the app asks.

With an API key instead of signing in (servers, CI, agents that run unattended), send it as a bearer token:

claude mcp add --transport http furniops https://mcp.furniops.com/mcp \
  --header "Authorization: Bearer $FURNIOPS_AGENT_KEY"

Signing inCopy Anchor Link

FurniOps sign-in is OAuth 2.1 with PKCE. The server publishes its Protected Resource Metadata (RFC 9728), which names FurniOps as the authorization server and the permissions a token may ask for.

• You choose the organisation and approve the permissions on a consent screen. Consent is always asked: no MCP client is trusted by default.
• A token holds at most what an API key may hold, and never more than your role: no client can manage keys, members, the organisation, billing or the agent.
• Tokens for the MCP server work only there, and API tokens do not work on the MCP server.
• If a tool needs a permission your token lacks, the server answers 403 with error="insufficient_scope" and the scope it needs. Clients that support step-up ask you to approve it.

ToolsCopy Anchor Link

The tools are generated from the API reference, one per route, named after the operation in snake_case (list_products, get_run, update_source). Each takes the route's path and query parameters at the top level, and a write's body as body.

Routes that hand out secrets (creating a webhook endpoint, rotating its secret) or change security are never tools, and neither are deciding proposals or changing the AI agents and the judge. Use the dashboard or the API for those. Some write tools also refuse fields a person must change: update_webhook_endpoint takes no url, so text a model reads can never redirect your events. A call that includes one is refused, not ignored.

Every toolCopy Anchor Link

Generated from the contracts release these docs are built from: the tool, the route it calls and the permission it needs.

Every tool states what it risks: readOnlyHint, destructiveHint (only delete_webhook_endpoint today) and idempotentHint. Clients use them to decide when to ask you before a call.

WritesCopy Anchor Link

Which keys may write. An API key is offered write tools only when its purpose is AI agent. Agent keys are always restricted to the permissions you pick, and when your organisation turns on agent key approval, a second member must approve one before it works. A key made for an integration or a third party gets read tools only, so a sync key can never be driven by a model.

Retries do nothing twice. Creating tools take an optional idempotency_key. Without one, the server makes a key for that call. A client that retries with its own key gets the first answer back, as with idempotent requests.

No lost updates. Reading a single resource returns its ETag, as a line of text and in the result's _meta["com.furniops/etag"]. Tools that change a resource (update_source, update_webhook_endpoint) take it as if_match. If someone changed the resource since, the call fails with precondition_failed: read it again and retry. See concurrency.

Results and errorsCopy Anchor Link

• A result is the route's JSON: as text, and as structuredContent when it is an object. Its shape is the route's response in the API reference. Tools carry input schemas only, so the tool list stays small enough for clients that budget tool definitions.
• A refusal is a tool error naming the problem's title, code and detail (and the fields, for invalid_request), so the model can tell not_found from permission_denied. It is not a protocol error. Codes are explained in errors.
• Results are data. Product titles, descriptions and notes come from supplier feeds and websites. Every result is marked as untrusted content, and the server tells the model never to follow instructions found in it, or change anything because the content asks.

LimitsCopy Anchor Link

• Plan: MCP is a plan feature. An organisation whose plan does not include it is answered 403 feature_unavailable.
• Rate: each signed-in caller (key or person, per mode) has its own budget for MCP requests: 50 a second, bursts of 200. Each tool call also takes your organisation's API rate budget, as the route it is. Callers never share a budget because they share an address, so hosted clients are not slowed by each other.
• Refused credentials: an address that sends more than 20 refused credentials a second (bursts of 200) is answered 429 for a moment, before anything is verified. Refresh expired tokens instead of retrying them.
• Quota: every tool call counts one MCP call in usage, and not an API call. Listing tools is free. When the month's quota is spent, tool calls return quota_exceeded until the next month; test mode is never capped. Counts reach usage within seconds.
• Requests are at most 1 MiB.

Test modeCopy Anchor Link

A test API key reaches only your sandbox, as on the API. A signed-in client works in live mode; send FurniOps-Mode: test with every request to use the sandbox. See test mode.

In the dashboardCopy Anchor Link

Developers › MCP shows the server URL, a ready-made setup for each client (signing in with OAuth, or an agent API key), what a client may do (read tools, write tools, and what is never a tool), and the limits. API keys for an agent are made under API keys.