API keys, MCP servers & widgets

API keys let your own apps and AI clients call Grey. To create one, go to Delivery → API Keys and choose New API Key.

• Name: required, up to 80 characters.
• Scopes: what the key can call. Retrieve (the retrieve endpoint) and Chat (chat completions) are selected to start with; MCP lets MCP clients connect with it. Pick at least one.
• Pipelines: leave it empty to allow every pipeline in the project, or select the ones the key can use.
• Rate limit (per minute): a whole number from 1 to 10,000. It starts at 60.
• Expires: optional, and it must be a future date.

Choose Create Key. The full key, starting with gk_live_, is shown once: copy it before you choose Done. Grey keeps only a fingerprint of it, so a lost key can't be shown again: revoke it and create a new one.

Managing keys needs the Manage API keys permission, which Owners and Admins have. Without it, New API Key is disabled, and hovering over it says why.

Grey serves a pipeline outside the app in three ways: the API, for your own code; MCP servers, for AI clients such as Claude Desktop and Cursor; and widgets, a chat bubble on your website.

All three answer with the pipeline's latest published version, so publish the pipeline first; see Publishing a version. Unlike the Playground, they always answer from the knowledge bases only.

Each request is recorded in Usage → Request Logs with its channel (API, MCP or Widget), and each answered request that retrieved passages counts as a retrieval in Usage & Costs. See Usage and request logs.

MCP Servers and Widgets depend on API Keys, so hiding API Keys from your sidebar hides them too.

Delivery → API Keys lists the project's keys with their scopes, pipelines, rate limit, when each was last used, when it expires and its status: Active, Revoked or Expired. Search by name or by the key's first characters.

Each key's ⋯ menu has:

• Revoke: asks you to confirm with Revoke Key. Requests using the key start failing straight away, and a revoked key can't be turned back on.
• Delete: asks you to confirm, then removes the key from the list for good.

Both need the Manage API keys permission.

Each pipeline's Endpoints section shows its Chat completions and Retrieve addresses, with copyable code samples. Send the key in the Authorization header as Bearer followed by the key.

• Chat completions works with OpenAI SDKs and tools: set the SDK's base URL to the pipeline's OpenAI base URL. The model you send is ignored, answers include their citations, and stream is supported. Only text messages work, and the last message must be the user's question.
• Retrieve returns matching passages without an answer. Send a query of up to 8,000 characters, and optionally topK (1 to 50), threshold (0 to 1) and kbIds, a subset of the pipeline's knowledge bases.

Calls fail when the key lacks the scope, isn't allowed on that pipeline, or is revoked or expired; when the pipeline isn't published yet; and when the key's rate limit is used up, in which case the response says how many seconds to wait.

An MCP server lets AI clients such as Claude Desktop and Cursor search your knowledge bases and ask your pipeline questions. To create one, go to Delivery → MCP Servers and choose New MCP Server.

• Name: required.
• Knowledge bases: the ones the server can search.
• Pipeline: required. It answers the server's questions.
• API key: optional. Clients connect with a key that has the MCP scope. Pick one here to accept only that key, or leave it empty to accept any of the project's keys with that scope. Only active keys are listed.
• Tools: what clients can call. search (search the knowledge bases) and ask (ask the pipeline) are on to start with; get_entity (look up a knowledge graph entity) and list_sources (list the sources) are off.

Choose Create Server. Managing MCP servers needs the Manage MCP servers permission, which Owners and Admins have.

Click a server in Delivery → MCP Servers to open its details. They show its Server URL, the tools it has turned on, and under Connect a client, a ready-made configuration on the Claude Desktop and Cursor tabs. Add it to claude_desktop_config.json or .cursor/mcp.json, and put your API key in place of the placeholder in its Authorization header.

The Status switch turns the server off without deleting it: clients are refused until you turn it back on. The list's ⋯ menu has Edit and Delete. Deleting asks you to confirm, connected clients stop working straight away, and it can't be undone. Each pipeline's Endpoints section also lists the MCP servers that use it.

A widget is a chat bubble you embed on your own website, answering visitors with one pipeline. To create one, go to Delivery → Widgets and choose New Widget.

• Name and Pipeline: required.
• API key: optional. Revoking the key turns the widget off, and the widget answers up to the key's rate limit each minute, or 60 without a key. The key is never sent to visitors' browsers.
• Allowed domains: the sites that can show the widget, like docs.example.com, or *.example.com for every subdomain (not the bare domain). Pages must use https. With no domains, the widget works nowhere.
• Title, Greeting and Placeholder: the text visitors see. They start as Chat with us, a greeting, and Type your question.
• Position: Left or Right (the default) corner of the page.
• White-label: hides the Powered by Grey footer.

The Preview shows the bubble and chat panel as you change them. Choose Create Widget. Managing widgets needs the Manage widgets permission, which Owners and Admins have.

Once a widget is saved, its Embed snippet appears in the widget's form. Paste it into your page before the closing body tag. Every site that embeds the widget must be in Allowed domains; other sites are refused.

Visitors' conversations appear in Playground → Conversations on the Widget channel. A visitor can send messages of up to 2,000 characters, up to 10 a minute, and a conversation can run to 50 turns before the widget asks them to start a new one.

Click a widget in the list to edit it. Each widget's ⋯ menu has Edit, Disable or Enable, and Delete. A disabled widget tells visitors it's turned off. Deleting asks you to confirm and can't be undone.