Pirros MCP connects an AI assistant to your firm's Pirros library. Once connected, you can ask it in plain English to find a detail and hand you its PDF or Revit file, trace what a family contains and what depends on it, or build a stash — in the same conversation you're already working in.
Pirros MCP is included with Pirros Max. Setup has two halves: a firm admin creates a credential once (Part 1), then each member connects their own assistant (Part 2). If your admin has already sent you a client ID, skip to Part 2.
Supported assistants: Claude Code, claude.ai, Cursor, Codex CLI, Codex in the ChatGPT desktop app, and ChatGPT on the web. The Claude desktop and mobile apps aren't covered — use Claude Code or claude.ai instead.
Building your own tool or script? It reaches the same tools but signs in with a secret your code holds. Choose A server, a script, or your own tool when you create the credential, and see Set up API access for your firm.
Before you turn this on
Admins: these follow from how connections work, and are hard to undo, so please read them before you open your first credential.
Anyone who connects gets the credential's full reach. Once Allow connections is on, any member of your firm can connect and reach everything the credential covers — including workspaces they can't open in Pirros. Their Pirros permissions don't narrow it.
Detail PDF links are permanent and public. They never expire, need no sign-in, and keep working after the connection is revoked — including copies sitting in the AI vendor's chat history.
Ending access applies to everyone on a credential. Turning off connections or revoking a credential disconnects every member on it. You can't disconnect one named person.
You see usage, not activity. Pirros shows how many members are connected and when the credential was last used — not who asked for what, or who downloaded what.
Part 1 — Set up the connection (Admins)
You'll need Pirros Max, the Manage API Keys permission, and admin rights on each workspace you want to open — the form only offers workspaces you administer.
Go to Settings → API Keys and click Create new API Key.
Under What is this credential for?, choose A supported AI client.
Under Which AI client?, pick the assistant your members will use: ChatGPT, Claude (claude.ai), Claude Code, Codex (the CLI and the ChatGPT desktop app), or Cursor.
Enter a Name and Description. Members see both when they connect, so name it for the client and purpose (for example, "Claude — structures team"), not for a person.
Tick the filters the credential may reach, and the actions on each: read, write and download (tags have read and write only). Without download, members can't get Revit files or a PDF that saves as a file. For a narrower slice, build a filter first in Settings → Resource Filters.
If a filter covers a whole library, tick the acknowledgement. Then click Generate.
Copy the Client ID and Client Secret, or click Download as .env file. Codex has no secret — the client ID is all it needs.
On the credentials page, turn on Allow connections. New credentials start closed, and nobody can connect until you turn this on.
ℹ️ The client, name and description can't be changed after Generate, so a credential made for the wrong client has to be replaced. Filters can be changed later with Edit scopes. Both values stay on the credential's page: Show reveals the secret, and each reveal is recorded in your firm's audit log.
Send each member three things
The Pirros MCP address: https://external-api.pirros.com/mcp
The client ID
The client secret (skip this for Codex)
Send the secret the way your firm sends any other secret. Members never need a workspace ID. For ChatGPT on the web, also tell them their ChatGPT workspace admin has to turn on Developer mode first — usually not the same person as their Pirros admin.
Best practices
One credential per AI client, one workspace per credential. A credential is the unit you revoke — if Cursor and ChatGPT share one, you can't end one without ending the other.
Mind the limit. A firm can hold 15 active credentials, shared with your firm's other API keys. If you run short, retire unused credentials first, then combine workspaces under one client before sharing a credential between clients.
End or narrow access
To… | Use | The credential afterwards |
Disconnect everyone, but let them reconnect | Disconnect all | Kept, and still open |
Disconnect everyone and stop new connections | Turn off Allow connections | Kept, but closed |
Retire it for good | Revoke | Gone — create a new one |
Narrow what it reaches | Edit scopes | Applies on the next request — nobody has to reconnect |
Replace a leaked secret | Regenerate secret | Kept, but every member needs the new secret |
When someone leaves your firm, their connection ends once their Pirros account is removed. Disconnect all is the only immediate option.
Part 2 — Connect your assistant (members)
From your admin you need the Pirros MCP address, a client ID and — for everything except Codex — a client secret. Enter the address in full, including /mcp at the end.
⚠️ Leave any bearer token or authorization header field empty. Filling one in stops the browser sign-in, and the client only reports that the connection failed.
Every client finishes the same way: your browser opens on Pirros, you sign in, and a consent page shows the credential, your firm, and the workspaces it reaches. Click Connect — nothing is connected until you do.
Claude Code
In a terminal, run:
claude mcp add -s user --transport http pirros https://external-api.pirros.com/mcp --
client-id <CLIENT ID> --client-secret
You'll be prompted for the secret, so it stays out of your shell history. Then type /mcp in Claude Code, choose the Pirros server, and choose Authenticate. To remove it: claude mcp remove pirros.
claude.ai
Go to Settings → Connectors → Add custom connector. Enter the Pirros MCP address, open the advanced settings, and enter the client ID and secret. Click Connect. To remove it, delete the connector in the same place.
Cursor
Add a Pirros entry to ~/.cursor/mcp.json. If the file doesn't exist yet, create it with the content below. If it already lists other servers, add just the "pirros" entry inside mcpServers, alongside them.
{ "mcpServers": { "pirros": { "url": "https://external-api.pirros.com/mcp", "auth": { "CLIENT_ID": "<CLIENT ID>", "CLIENT_SECRET": "<CLIENT SECRET>" } } } }
Cursor doesn't open the browser on its own: go to Settings → Customize → Tools & MCP and choose Authenticate on the Pirros entry. Before your first request, set the chat's run location to This Mac, and decline if Cursor offers to create a namespace — chats running in Cursor's cloud won't use this connection. To remove it, delete the entry from mcp.json.
Codex CLI
codex mcp add pirros --url https://external-api.pirros.com/mcp --oauth-client-id <CLIENT ID>
This starts the browser sign-in straight away. On macOS, choose Always Allow when asked about the keychain. If you see Dynamic client registration not supported, the client ID was missing — run codex mcp remove pirros and try again. To sign in again later: codex mcp login pirros. To remove it: codex mcp logout pirros, then codex mcp remove pirros.
Codex in the ChatGPT desktop app
The app has no field for a client ID, so connect through the Codex CLI: run the command above, finish the sign-in, then quit and reopen the app. Pirros then appears under Settings → Integrations → Plugins → MCPs, already signed in.
The app can also drive your browser, and may open the Pirros website instead of using the connection. Start your requests with "Use the pirros MCP server tools only, not the browser and not computer use." — and don't sign in to the website if it opens.
ChatGPT on the web
First, your ChatGPT workspace admin must turn on Developer mode — without it there's no way to add a custom plugin. Set the plugin up on the web; the desktop app can't create it.
Go to Plugins → + → New Plugin. Enter a name, paste the Pirros MCP address as the Server URL, and set Authentication to OAuth.
Open Advanced OAuth settings. Set Registration method to User-Defined OAuth Client, enter the client ID and secret, and set Token endpoint auth method to client_secret_post — the default, none, fails after you sign in. Leave the scopes and endpoints as they are.
Tick the acknowledgement and click Create, then click Connect on the new plugin to sign in.
If Pirros adds or changes tools, refresh the plugin from its ⋯ → Manage → Refresh menu.
Disconnect your assistant
In Pirros, go to Settings → Profile. The Pirros MCP section lists each credential you're connected through — click Disconnect to end all of your sessions on it. Nobody else is affected. A connection also lapses after about a month without use, or when your admin ends it; reconnect the same way.
Client menus and commands change often. If a step above has moved, the client's own documentation is authoritative.
Check that it works
A client that says it's connected has only proved the sign-in finished. Ask these three questions, in order:
Which Pirros workspaces can this connection reach, and what is it allowed to do in each?
What tags exist in that workspace?
Find details matching "<a word you know is in your drawings>" in that workspace.
If all three work, you're set. If the first works but the third comes back empty, the connection is fine — the content is outside what the credential reaches. If the workspace names aren't the ones you expected, ask your admin.
What you can ask for
Details: find them by text, tag, detail type, Revit year or sheet number; open one for its sheet, detail number, scale and notes; get its PDF, and its Revit file if the credential has download.
Families: find them by text, tag, category or Revit year; see a family's revision history, what's nested inside it and which families reference it; check for near-duplicates; get the .rfa.
Tags: list a workspace's tags.
Stashes: create one from details and families, rename it, mark it permanent, and read it back.
For better answers:
Start with "In Pirros, …" and name the workspace in your first request. You never need an ID — describe things the way you would to a colleague.
Narrow, don't page. Add a tag, sheet number or Revit year rather than asking it to go through everything.
When several items share a name, say which one — the sheet number for a detail, the category or Revit version for a family.
Be precise about changes. Cursor doesn't ask before writing, and ChatGPT doesn't ask before creating a stash. "Put these three details in a stash called Curtain wall review" is safe; "tidy these up" isn't.
Check any value you'll build to — a scale or a sheet number — against the PDF.
For example: In Pirros, find the detail called "HORIZONTAL BRACE TO SLOPING COLUMN" in the Studio Library workspace — tell me which sheet it's on and give me its PDF.
Download links
Detail PDF links are permanent and public. Anyone with the link can open the drawing, even after the connection is revoked. Treat one like the PDF itself.
Revit links (.rvt and .rfa) expire after about 15 minutes — ask for a fresh one if it lapses. They save without a file name, so rename the file to end in .rvt (detail) or .rfa (family).
Revit files, and PDFs that save as a file, need the download action. Without it, the request comes back as if nothing was found.
If your firm has switched downloads off for an item, its Revit file and save-as-file PDF are refused. That's a policy setting, not a fault — the regular PDF link still works.
In ChatGPT, Revit links break because ChatGPT adds utm_source=chatgpt.com to the end. Delete it, or ask for the link as plain text.
What it can't do yet
These reflect what the Pirros API exposes today; the assistant picks up new abilities as the API grows.
No totals or counts — "how many details do we have?" has no answer.
No project names, and no filtering by project.
No list of your stashes, and no finding one by name — open stashes in Pirros. Stashes can't be deleted through an assistant either.
A stash's items are fixed when it's created and must all come from one project (up to 500 items). Only the name, description and permanent flag can change afterwards. Stashes you create this way belong to you.
Some lists are capped: 500 tags, 20 similar families, and 100 families on nested or referencing lists.
Troubleshooting
If the consent page says… | Do this |
This connection request has expired | Requests stay open for ten minutes. Start again from your client. |
Pirros could not sign you in, or This sign-in has expired | Start again from your client. |
This sign-in has no Pirros account, or This credential belongs to another firm | Sign in with the account your firm invited. |
Connecting with this credential is turned off | Ask your admin to turn on Allow connections. |
This credential can no longer be used | Ask your admin for a current credential. |
Your firm's plan does not include Pirros MCP | Pirros MCP comes with Pirros Max. Ask your admin to contact Pirros. |
An error page before the consent page usually means the credential was made for a different AI client. Ask your admin for one made for the client you use.
The connection fails with no explanation: check that the address ends in /mcp and that no bearer token or authorization header is set.
It worked, then suddenly fails (Cursor shows a red entry, Codex says no workspace is connected): the credential's hourly allowance, shared by everyone on it, is probably used up. Don't reconnect — a new sign-in draws on the same allowance. Wait and try again, and tell your admin if it keeps happening.
It can't find a drawing you know exists: ask the first check question. The drawing may be outside what the credential reaches.
Related articles
Stuck? Members, start with your firm's Pirros admin. Admins, contact [email protected].