Skip to main content
The MCP server accepts two kinds of credential. Both read the same data, through the same scopes and brand limits: Only the workspace owner and integration admins can approve a sign-in or create a key. Other members can see both lists.

Sign in with OAuth

When a client that supports MCP sign-in connects to https://app.usequotable.com/api/mcp without a credential, Quotable answers 401 and tells the client where to sign in. The client opens a Quotable page in your browser.
1

Sign in to Quotable

If you aren’t signed in, sign in as usual, including your second factor or single sign-on. You come back to the approval page afterwards.
2

Check who is asking

Check the app’s name and the address it sends you back to, such as claude.ai or chatgpt.com. If either looks unfamiliar, click Cancel. Some connections also ask you to tick I started this connection myself.
3

Pick the workspace

The connection reads one workspace: the one you’re working in. If you belong to several, switch with the buttons under Use another workspace.
4

Pick the data and the brands

Untick any data the app doesn’t need, and leave Every brand ticked or choose specific brands. The app can never get more than the app asked for and you ticked. Run agents and Edit facts let the app act, not only read. They appear only when the app asks for them, and they start unticked.
5

Allow access

Click Allow access. Your browser returns to the app, which finishes connecting. Cancel tells the app you declined.
Approval links expire after ten minutes and work once. If the page says the request expired, start the connection again from the app. If you switch workspace in another tab while the page is open, Allow access asks you to reload, so you never approve a workspace you didn’t see.
If your sign-in isn’t recent, Quotable asks you to sign in again or confirm your second factor before you can allow access. It’s the same check as creating an API key.

How long a connection lasts

The client receives an access token that lasts one hour and a refresh token it uses to get the next one, so you don’t sign in again every hour. If a refresh token goes unused for 30 days, the client asks you to sign in again. A refresh always returns exactly the data you approved, whatever scope the client sends. A connection stops working, and the client asks you to sign in again, when:
  • someone disconnects it in Settings → MCP;
  • the client signs out of Quotable;
  • the person who approved it leaves the workspace or loses the access it needs;
  • Quotable detects a possible problem with the connection’s tokens and ends it to be safe.

Connected apps

Settings → MCP lists every approved connection under Connected apps: the app’s name and address, the data and brands it reads, who approved it and when, and when it was last used. The owner and integration admins can click Disconnect; it takes effect on the app’s next request. Approving and disconnecting are recorded in the audit log.
OAuth tokens are bound to the MCP server. The REST API doesn’t accept them; use an API key there.

For client developers

Quotable follows the MCP authorization specification: The authorization response includes iss. If a client asks for no scope Quotable knows, the approval page offers every read scope. A write scope is offered only when the client asks for it by name, and it starts unticked. Errors in the authorization request (a missing PKCE challenge, an unsupported response_type, another resource) are sent back to the redirect URI only for clients identified by a metadata document. For other clients they’re shown on a Quotable page instead. scope on a refresh request is ignored.

Use an API key

API keys suit clients that can send a fixed header, and scripts. The client sends the key in the Authorization header on every request:

Create a key

1

Open API keys

In Quotable, go to Settings → API keys and click Create API key. Only the workspace owner and integration admins can create and revoke keys. Other members can see the list of keys.
2

Pick what the key can reach

Under Scope, choose Brand for the brand you’re working in only, or Workspace for every brand you can open. A key limited to one brand can’t read any other brand.
3

Name it after the client

Use a name that says where the key lives, such as “Claude Code – Maria” or “Cursor – content team”. The name appears in the key list next to the key’s last-used date.
4

Copy the key

Click Create key. The full key, starting with quotable_live_, is shown once. Copy it into your client’s configuration or your secret manager right away. It can’t be shown again.
A key created in Settings → API keys gets every scope, including Run agents and Edit facts, and doesn’t expire. What it can reach is set by the brand or workspace you pick. A workspace can hold up to 25 active keys.
When an integration admin creates a Workspace key, the key covers the brands that admin can access at that moment. Brands added later aren’t included. Workspace keys created by the owner also cover brands added later.

Scopes by tool

Each tool requires one scope. Scopes are deny-by-default: a key or a connection can call only the tools whose scope it was granted. On the approval page, the settings label is what you tick. read:facts (Facts) and write:facts (Edit facts) are used by the REST API’s facts endpoints. No MCP tool uses them.
Always grant read:projects. Every other tool takes a brand id, and your assistant gets those ids from list_projects.
Any valid key can connect and list the tools, whatever its scopes. Your client shows every tool. When the assistant calls a tool the key or connection wasn’t granted, the call returns an error instead of data:
To fix it, disconnect the app and sign in again ticking that data, or create a new key. You can’t add scopes to an existing key or connection.

Common scope sets

These apply to OAuth connections, where you tick the data on the approval page.

Limit a key or connection to some brands

A brand list applies to every tool. list_projects returns only those brands, and any other tool called with a brand id outside the list answers as if the brand doesn’t exist:
Both cases read the same on purpose, so a client can’t discover brands it wasn’t given.
The API calls brands “projects”. The project_id that tools take is a brand’s id.
A signed-in connection has no long-lived secret to copy into a file, renews itself, and shows up under Connected apps with who approved it.
Give each AI client its own key. When someone leaves or a laptop is lost, you revoke that key without breaking anyone else’s setup, and the last-used date tells you which clients are active.
On the approval page, untick data the app doesn’t need. A connection for a visibility report doesn’t need Run agents. For keys, pick Brand when one brand is enough: an agency key for one client needs only that client’s brand.
Keys created in the app don’t expire. Check the last-used dates in Settings → API keys and revoke keys that are no longer in use.
Don’t commit keys to a repository. Most clients can read the key from an environment variable or prompt for it. Each connect guide shows how.

Revoke a key or disconnect an app

In Settings → API keys, click Revoke next to the key. Revoking takes effect on the next request: a connected client is refused on its very next tool call with 401 and “This API key was revoked.” A key also stops working when the person who created it leaves the workspace or loses the access the key needs. Requests then fail with “The API key creator no longer has the required access.” Create a new key from an active owner or integration admin. To end an OAuth connection, click Disconnect next to it under Connected apps. The app’s next request gets 401 and it asks you to sign in again.

Next steps

Connect a client

Step-by-step setup for each client.

Tools reference

Exactly what each tool returns.

Troubleshooting

Every error message and what to do about it.
Last modified on November 18, 2026