Twelfth
Read your Twelfth retail workspace through permission-scoped, read-only MCP tools.
Hosted MCP Server
npx add-mcp 'https://api.twelfth.ai/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Any assistant that speaks the Model Context Protocol (MCP) can connect to a
twelfth workspace, even if it isn’t in the named list. twelfth exposes an MCP
endpoint at https://api.twelfth.ai/mcp, read-only unless you allow changes. It accepts an OAuth
user token or a workspace bearer key. Reach the setup guide from Settings →
AI tools → Generic MCP.
Use this when your client isn’t Claude,
ChatGPT,
Gemini,
Grok,
Glean,
Databricks,
Cursor,
Claude Desktop, or
VS Code / Copilot. The pattern is
the same for every MCP client. More assistants
has the exact steps for Perplexity, Mistral Le Chat, Gemini Enterprise, Amazon
Quick, Kiro, JetBrains Junie, Zed, Warp and Goose.
Connect with OAuth
If your client supports OAuth for a remote MCP server, add
https://api.twelfth.ai/mcp as the server URL. twelfth’s discovery metadata
starts the sign-in flow. Choose a workspace and allowed read tools on the
consent screen. This connection reads as you, within your workspace role and
remits; no key needs to be copied. End it from Settings → AI tools.
If you are signed out, twelfth asks you to sign in before showing consent. The
connection requires an existing account and a workspace you belong to. If you
do not have an account, choose Book a demo from the sign-in page to request
access. If you have an account but no workspace, accept an invitation, create a
workspace, or book a demo for help getting started.
Connect with a workspace key
- In twelfth, open Settings → AI tools, go to the Settings tab and, under API keys, choose Connect an agent → Generic MCP. twelfth creates a key for this connection, copies it to your clipboard, and starts waiting for Generic MCP’s first request. Copy the key now if you need it again. twelfth shows it only once.
- In your client’s MCP configuration, add a server with:
- URL / endpoint: the twelfth endpoint shown on the connection’s row.
- Authorization: a bearer token set to the key you generated.
- URL / endpoint: the twelfth endpoint shown on the connection’s row.
- Reload the client’s MCP servers, then ask it to list twelfth’s tools to confirm the connection.
Allow changes
The consent screen also offers Allow changes, off unless you turn it on. With it on, an OAuth connection can use these tools, acting as you. They touch only your own things, so new tools of this kind reach the connection automatically, without reconnecting:
twelfth_complete_action: mark one of your open actions done. A price review or price change closes as reviewed, no action: prices are only changed in twelfth.twelfth_snooze_action: hide one until tomorrow or next week.twelfth_create_action: create a task for you, with a title and details.twelfth_run_routine: run one of your own routines.twelfth_set_routine_paused: pause or resume one of your own routines. Archiving stays in twelfth, where it is confirmed.twelfth_mute_routine_product: stop one of your own routines flagging a product, until a day you choose or until you unmute it.twelfth_update_my_settings: change one of your own settings, such as your theme, default chat model or notifications. Send the revisiontwelfth_get_settingsgave; if the setting changed since, nothing is written. It never changes a workspace setting.
Tools that need your approval
Tools that change things for the whole workspace, or reach other people, are never added to a connection without your approval. Under Allow changes, the consent screen lists them one by one, each off until you turn it on:
twelfth_update_settings: change one setting thattwelfth_get_settingslists as changeable, such as a retailer’s chart colour (your own line included), or a workspace default such as tax display or the authority limit. Send the revision you read; if the setting changed since, nothing is written. Workspace settings need an owner or admin, and two-factor where the workspace requires it. When a member asks for a workspace change, it is emailed to the workspace’s owners and admins as a request instead, and they apply or decline it in Settings.twelfth_update_agent_policy: twelfth staff with workspace owner/admin access can update managed chat defaults. Requires workspace MFA when enforced.
When twelfth adds a tool like these, or you skipped one at consent, your connection’s row in Settings → AI tools shows it as approve to use. Choose Review new permissions to see what the connection already allows beside what approving adds, then approve the tools you want; the assistant can use them from its next request, with no reconnect. Connecting an assistant you already connected shows the same: the consent screen starts from what your latest connection allows and marks the new tools, which stay off unless you turn them on. Approving adds a new connection beside the existing one, which keeps its own access until you end it. Only the person a connection reads as can approve its tools. An assistant that keeps a change stream open is told its tool list changed.
Every change follows the same rules as the app, and every call is recorded against the connection. A workspace setting change is also recorded in the workspace’s audit events. Figures, prices, orders, security and sign-in, members, integrations and the settings twelfth manages (timezone, currency, country) cannot be changed over MCP; twelfth_get_settings lists each of these with the reason. Runtime access is always restricted to current twelfth staff workspace admins; an older grant cannot bypass that restriction. A connection made without Allow changes, or before it existed, never sees any of these tools; to turn Allow changes on or off, connect again. Workspace keys never make changes. Extensions has the details.
Available tools
The connection reads, unless you allowed changes. Its available tools depend on its saved selection,
the workspace’s capabilities and, for OAuth, the member’s permissions. They
include:
- Get workspace identity and operating defaults.
- List workspace members and their roles.
- List open actions, including due dates, assignees, and available source context.
- Read-only analysis tools for the visible task snapshot and the caller’s readable catalogue: sales metrics, product ranking, inventory position, product master, similar products, supplier constraints, supplier lookup, entity profiles and context, and methodology. Connected workspaces can also offer competitor price intelligence. Arbitrary warehouse SQL is reserved for twelfth’s staff-only diagnostic workspace.
Tools that only make sense inside the in-app chat (asking the buyer a clarifying question, rendering a table or chart) are not offered over MCP. Tool results include source_evidence_ids; a later call can pass them back to refer to the same rows.
An MCP key is a workspace credential and belongs to no one person. It reads the whole business, the way the owner or admin who created it does, and is not narrowed to any one buyer’s remit.
Apart from the approved Allow changes tools, these tools cannot write data or make changes in twelfth.
Prompts and resources
Clients that support MCP prompts can offer twelfth’s ready-made briefs, often as
slash-commands: Weekly trading brief, Explain a recommendation,
Competitor price check, Supplier review and Project status. Each one
walks the assistant through the read-only tools above.
Clients that support MCP resources can pin standing context: the workspace,
open actions, members and, where the workspace has them, project
workflows, category settings, tracked pricing sets and integrations. A
resource shows only what its matching tool would, so a connection limited to
certain tools sees only those resources.
Events
An assistant can also watch the workspace and act when something changes:
new recommendations, competitor price moves, project changes, or a fresh day of
data. See Events.
What twelfth records about a connection
Every call is logged against its connection: the tool name, whether it succeeded,
when, and how long it took. Tool results are never stored or sent to analytics;
only their size is. Workspace keys are stored hashed and shown once, at creation.
Repeated failed authentication from one address is refused for a cooling-off
period.
Plugins and listings
Where twelfth is, or will be, listed:
- Claude (Claude Connectors Directory): listing in review. Until then, add twelfth as a custom connector.
- ChatGPT: install twelfth from the marketplace, then sign in and choose your workspace. See the ChatGPT setup guide.
- Codex: connect by command (below).
- Microsoft Copilot: get twelfth from Microsoft Marketplace for Microsoft 365 Copilot in Teams, Outlook and the Microsoft 365 app, then sign in and choose your workspace. For Copilot Studio, use Copy install prompt in Settings → AI tools → Connect AI.
In Codex:
codex mcp add twelfth --url https://api.twelfth.ai/mcp && codex mcp login twelfth
twelfth’s server is published in the
Official MCP Registry
as ai.twelfth/workspace, from the twelfth.ai domain. Clients and directories
that read the registry can find it there.
The open-source twelfth-ai/twelfth-mcp
repository holds the client side: the MCP configuration, a plugin for
Cursor and
Claude Code, and a skill that helps an assistant use the tools well. In Claude
Code:
/plugin marketplace add twelfth-ai/twelfth-mcp
/plugin install twelfth@twelfth
The repository contains configuration only. The server itself is hosted by
twelfth, and every connection still signs in and follows your workspace
permissions.
Support
Email hello@twelfth.ai with any question about
connecting an assistant, a tool that returns something unexpected, or access to
your workspace. You can also use the form at
twelfth.ai/contact. Include the assistant you are
using (for example Microsoft Copilot, Claude or ChatGPT), the workspace name and
roughly when it happened, so we can find the request.
To use the connector you need an active twelfth account in a twelfth workspace.
To get one, book a demo.
Related
- AI tools overview: the shared connect flow and available tools
- Events: let an assistant watch for changes
- API keys: create, name, tag, and revoke keys
- Vercel Connect: use twelfth MCP from a Vercel app or agent