Getting started

Connect your AI client to your orgs (MCP)

Drive your Salesforce orgs from ChatGPT, Claude or your own editor using your AI subscription — paste a URL, sign in, choose scopes, and see exactly what it can and cannot do.

7 min read

orgadmin.ai can act as an MCP server — a set of tools that an outside AI app connects to and drives: ChatGPT, Claude, your IDE's AI assistant, an agent CLI, or anything else that speaks MCP. Instead of this app paying for AI and metering your tokens, your own AI subscription pays for the thinking and orgadmin.ai just supplies the Salesforce capability. No AI provider key needed here, no token allowance consumed.

In practice: you paste one URL into your AI app, sign in to orgadmin.ai once, and from then on you ask for something in plain English and your assistant reaches into your connected orgs to answer — reading schema, Apex, flows and live data, and (if you allow it) changing records.

This is an alternative to the in-app assistant, not a replacement

The built-in AI chat still works exactly as before and is the easier starting point. MCP is for people who already work in ChatGPT, Claude or an AI-enabled editor and want their Salesforce org available there.

How it works

MCP (Model Context Protocol) is an open standard for giving an AI app tools it can call. orgadmin.ai exposes one endpoint — /api/mcp — that speaks it.

You connect by pasting that URL into your AI app. The app sends you to an orgadmin.ai sign-in and consent screen, you choose what it may do and click Allow, and the app is connected. This is standard OAuth — the same “Sign in with…” flow you know from elsewhere — so there is no secret to copy and the app keeps itself signed in. Clients that can't open a browser (CI jobs, remote shells) use a personal access token instead, which you create in Settings.

Either way, every tool call lands back in the same machinery the web UI uses: the same tenant checks, the same workspace roles, the same read-only Salesforce client, and the same audit log. A connection is a view onto what you can already do — it can never exceed your own access.

Before you start

  • The feature must be switched on for your deployment. It ships off, because it opens a new authenticated endpoint. If the MCP card in Settings shows a warning, an operator needs to enable it.
  • A plan that includes MCP access. The consent screen tells you if yours doesn't.
  • At least one connected Salesforce org — see Connect your Salesforce orgs. MCP cannot connect an org for you; that needs a browser sign-in.
  • An AI app that supports remote MCP servers — ChatGPT (with developer mode on), Claude on the web, desktop or mobile (custom connectors), Claude Code, Codex, and most AI-enabled editors.

Step 1 — Add the server URL to your AI app

Everything starts from one URL. It's also on the MCP access card in Settings, with a copy button:

https://orgadmin.ai/api/mcp

Where it goes depends on the app:

  • Claude (claude.ai, the desktop app, mobile) — Settings → Connectors → Add custom connector. Paste the URL and click Add, then Connect.
  • ChatGPT — Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector with the URL and OAuth as the authentication.
  • Claude Code — claude mcp add --transport http --scope user orgadmin https://orgadmin.ai/api/mcp, then /mcp → Authenticate.
  • Any other app — add a remote MCP server with this URL and the HTTP (streamable HTTP) transport, not SSE or stdio. If it supports OAuth it will offer to sign in; if not, use a personal access token.

Click-by-click for each app

Connect ChatGPT, Claude, Claude Code & Codex walks through each one, including what a working connection looks like and what to do when one won't connect.

Step 2 — Sign in and choose what it may do

When you click Connect, your AI app opens an orgadmin.ai page. Sign in if you are asked to — with your password or with Salesforce, the same as always — and you land on a consent screen that shows:

  • Which app is asking, and the site it will send you back to (for example claude.ai or chatgpt.com). If that site isn't the app you just clicked Connect in, cancel.
  • Which account you're signed in as, with a “Not you?” link to switch.
  • What the app may do — one tick box per scope. Scopes are the main safety control here, and they do more than refuse calls: a tool outside your scopes is never shown to the AI at all, so it can't attempt something and fail. Fewer scopes also means a shorter tool list, which makes the AI pick the right tool more reliably.
    • org:read — read everything: objects and fields, Apex, LWC, flows, other metadata types, debug logs, and read-only SOQL. No changes of any kind. Always ticked to start with, and enough for most work.
    • org:write — lets the AI build inside orgadmin.ai: Development Studio projects (pull components in and edit the code), durable facts about your org (the same notes the in-app assistant keeps), and saved dashboards, reports and charts on your Insights page. Never changes anything in Salesforce — project edits stay here until you deploy them, and the queries behind an insight are read-only.
    • data:write — insert, update, upsert and delete records in Salesforce. Real changes to real data. It always starts unticked, even if the app asked for it — tick it only if you want it.
    • users:write — deactivate or reactivate a Salesforce user, and assign or remove their permission sets and permission set groups, production included. It takes effect in Salesforce immediately, and it also starts unticked.
    • deploy — validate a Development Studio project against any org, and deploy it to a sandbox. Production deploys stay a click in the Studio. It also starts unticked.
    • chat — ask orgadmin.ai's own assistant about an org and read your saved chats for it. Replies use your monthly AI allowance. The orgadmin.ai phone apps ask for this.
  • Which orgs it may use — one dropdown per connected org: Full access (whatever you ticked above), Read only (reading tools and the assistant only, so nothing is changed in that org whatever you ticked), or Off (the AI can't see the org at all). Production orgs start read only and sandboxes full access — so “read production, build and change records in the sandbox” is the default. A last dropdown sets what happens for orgs you connect later; it starts at read only, so connecting a new production org never quietly hands an app write access to it.

Click Allow and you're sent back to the app, connected. It stays signed in from then on, renewing itself quietly in the background, and shows up in Settings → MCP access as a connected app you can disconnect at any time.

Changing what an app may do later

Org access can be changed any time: in Settings → MCP access, click Orgs on the app's row. It applies from the app's very next call. Scopes are fixed when you click Allow; to change them, connect the app again (in Claude or ChatGPT, disconnect and reconnect the connector) and tick a different set. The new connection replaces the old one automatically.

Step 3 — Try it

Confirm the connection in one step

Ask your assistant to “use the whoami tool”. It reports which orgadmin.ai account the connection is authenticated as, its name, and exactly which scopes it was granted — the fastest way to explain a surprising permission error, and proof the server is reachable.

Good first asks, in rough order of ambition:

  • “List my connected Salesforce orgs.” — proves the connection.
  • “What fields are on Opportunity in my sandbox?” — note you can name an org the way you named it here; you don't need to paste an id.
  • “What automation runs on Account, and is any of it likely to conflict?”
  • “Find every Apex class that references Loan__c and tell me which ones do DML in a loop.”
  • “Build me a pipeline dashboard for production — open opportunities by stage and owner, with a date filter.” — needs org:write; it lands on your Insights page.

The server also ships ready-made prompts, which clients that support them usually surface behind a / menu: explore_org for an orientation on an unfamiliar org, investigate_error to work backwards from a debug log, security_review and tech_debt_scan to run either audit and record it here, build_metadata for writing Apex or flow XML grounded in what the org already does, build_react_app for a React app that runs on Salesforce, and build_insight for a dashboard, report or chart. They exist because they carry the ordering knowledge — check automation before proposing a trigger, confirm field names before writing SOQL, verify every tile before saving a dashboard — that the in-app assistant gets from its own system prompt.

Using a personal access token instead

Signing in through the browser is the easy path, but it needs a browser. For a CI job, a remote shell, Codex, the Claude Desktop extension, or an app that doesn't support OAuth, create a personal access token and send it as a header.

  1. 1

    Open Settings → MCP access

    Go to Settings and find Personal access tokens on the MCP access card.
  2. 2

    Name the token after the machine that will use it

    Something like CI runner or work desktop CLI. You'll thank yourself when you have three of them and need to revoke one.
  3. 3

    Choose what it may do

    The same scopes as the consent screen in Step 2. Tick only what you need.
  4. 4

    Limit it to certain orgs, if you like

    A new token can use every org. Once it's created, click Orgs on its row to set each org to full access, read only or off — the same choices as the consent screen.
  5. 5

    Copy the token immediately

    It is shown once. Only a hash is stored, so nobody — including us — can show it to you again. Lose it and you revoke it and make another.
The MCP access card in Settings, with the token name field and scope picker
Name the token after the machine it lives on, then grant only the scopes that client needs.

Then add the server to your client with these three things:

  • URL — https://orgadmin.ai/api/mcp
  • Transport — HTTP (streamable HTTP). Not stdio, and not SSE.
  • Header — name Authorization, value Bearer oamcp_your-token-here (the word Bearer, a space, then your token).

Local AI & other tools

For tools that cannot sign in through a browser — LM Studio, Ollama front ends, agent frameworks, CI. The config shape most MCP clients read; transport is HTTP, not SSE or stdio.

  1. Add the server to your client config — If an mcpServers block already exists, add this entry alongside the others rather than replacing them. Some clients name the top-level key servers, and some use serverUrl in place of url.
    {
      "mcpServers": {
        "orgadmin": {
          "type": "http",
          "url": "https://orgadmin.ai/api/mcp",
          "headers": {
            "Authorization": "Bearer oamcp_your-token-here"
          }
        }
      }
    }
  2. Confirm the connection and the token in one step — It reports which account the connection is authenticated as, the token’s name, and the scopes it was granted.

Where that file lives is the one thing that differs per tool, and your tool's own docs will name the path. Two variations worth knowing if the block above is rejected:

  • Some clients name the top-level key servers instead of mcpServers.
  • Some use serverUrl instead of url, or infer the transport from the URL and reject type.

Keep the token out of shared files

The config above contains a live credential. If the file is inside a repository, make sure it is gitignored — or use your client's environment-variable syntax for the header value if it supports one.

What it can do

With org:read, your AI client gets 45 tools. Twenty-three more unlock with the write scopes.

  • Find your way around — list the connected orgs (with sandbox vs production and your role), read Company Information: edition, org id, instance, locale and fiscal year, storage and API usage, and licence counts.
  • Schema — list objects, describe one object's fields, relationships, picklist values and record types, and read the configuration defined on an object: record types, validation rules, page layouts, Lightning pages.
  • Automation — everything that runs on one object in a single call: Apex triggers, record-triggered flows with their timing, workflow rules and validation rules. This is the one to reach for before adding automation.
  • Flows — list every flow and Process Builder process with its kind, trigger object, active state and version history, then read one flow's logic: its elements in order, the Apex it invokes and the subflows it calls. It reads the active version by default — the one that actually runs — and the complete raw definition is one flag away.
  • Any metadata type — discover which types exist in the org, list their components, then read full definitions: workflow rules, approval processes, custom labels, named credentials and more.
  • Code — list and read Apex classes and triggers, and LWC bundle files (HTML/JS/CSS/meta).
  • Debug logs — list captured logs, filter to failures, and read a full execution trace to pinpoint an error, find the slowest SOQL, or read governor-limit usage.
  • Live data — run read-only SOQL. SELECT only; anything else is rejected outright.
  • Search — full-text search across cached metadata to find where something is referenced, which is how you do impact analysis before a change.
  • Deployment results — read what happened when you deployed or validated: the component compile errors and Apex test failures, each with its line number. This is what lets your assistant fix the error that actually happened instead of the one it guessed at. It still can't start a deployment.
  • Deep links — turn a record id or component into a real Salesforce URL you can click, using your own Salesforce session.
  • Skills — load the same Salesforce domain playbooks the in-app assistant uses before it writes Apex, flow XML or permission sets.
  • Insights — list what you've built on the Insights page and read how any of it is calculated.
  • Past audits — read any Security Review or Tech Debt run: the score, the coverage matrix, every finding, and what still needs checking by hand. Also installed packages with their licence usage, which is how you spot an app that's installed and assigned to nobody.
  • With org:write — build a change in a project. Ask your assistant to start a Development Studio project, pull in the Apex classes, Lightning components and metadata it touches, and edit them. Every edit is saved here as a draft, and each finished change is recorded as a version you can read the diff of and roll back. Keep the project open while your assistant works and you will see each component appear and change as it lands — no refresh, and anything you are part-way through typing is kept. Then you open the project, review it, and deploy. The AI has no deploy or validate tool — that step is yours.
    Big files are handled in pieces, which is why a four-thousand-line class or component works: your assistant searches the project for the line it wants, reads a window around it rather than the whole file, and writes a long file in parts that appear in your editor one after another.
  • With org:write — build a React app that runs on Salesforce. Ask for “a React app where reps can look up an account and log a call” and your assistant starts one in a project from a working template — routing, live Salesforce data through GraphQL, Tailwind styling, and the Lightning app and permission set that put it in the App Launcher — then shapes it into what you asked for. It can build the app here to check it, with every error reported by file and line, and it is expected to leave you an app that builds. As with everything else, you deploy it. See React apps in the Development Studio.
  • With org:write — create custom objects and fields. Ask for “a restricted picklist on Account with three values” and your assistant builds the metadata from a structured description rather than hand-writing XML, so the field type, length, picklist values and relationship targets are checked before anything is written. Adding fields to an object that already exists produces a fields-only file, which deploys the fields and leaves the object itself untouched. It all lands in a project for you to review and deploy — same rule as above.
  • With org:write — save a durable org fact to orgadmin.ai's knowledge base, shared with your teammates and visible on the Org Context page, and build dashboards, reports and charts from your own editor: your assistant writes the SOQL, verifies every tile against the live org, and saves the result to your Insights page. These are orgadmin.ai assets — not Salesforce Reports and Dashboards, and nothing is deployed to the org.
  • With org:write — run a Security Review or a Tech Debt scan from your own client. Ask for either audit and your assistant drives it here: for a Security Review it opens a run, works through the fourteen audit modules — those still execute on our side, because they need Tooling and Metadata API reads — reads the evidence each returns, and adds its own judgment findings on top. For Tech Debt it sweeps with the read tools and posts candidates as it goes. Either way the run lands on the normal page, filling in while you watch, and you triage it exactly as if you'd clicked the button yourself. Results are saved at every step, so a review that's interrupted halfway keeps everything up to that point. Because your own client does the thinking, these runs use none of your workspace's AI tokens.
  • With data:write — insert, update, upsert or delete records.
  • With users:write — activate or deactivate users, and assign or remove permission sets and permission set groups.
  • With deploy — validate and ship to a sandbox. Once a Development Studio project is saved, your assistant can run a check-only validation against any org (nothing changes there), read the compile errors and test failures, fix them and try again — then deploy the finished project to a sandbox. It deploys the project's last saved version, waits for your go-ahead when teammates are working on the same components, and every run appears under Deployments.

Your orgs and the skill library are also exposed as resources, so you can attach “which org am I working on” to a conversation once instead of restating it.

What it can't do

Deliberate limits, and current ones. Both matter before you plan around it.

Not supported today

  • orgadmin.ai isn't listed in the ChatGPT or Claude app directories. You add it yourself as a custom connector by pasting the URL — which works on every plan of theirs that allows custom connectors. In ChatGPT that means switching on developer mode first.
  • The extension is Claude Desktop's format, not a universal one. .mcpb bundles install into Claude Desktop; ChatGPT and Codex don't read them. The Claude connector works in the desktop app too and needs no bundle at all.
  • Deploying to production isn't available over MCP — by design. The AI can build a project, validate it against production and deploy it to a sandbox; the production deploy itself is yours, from the project or from Deployments, where the target, the Apex test level and the diff are in front of a person. deploy_project checks the target with Salesforce itself and refuses a production org whatever the token holds.
  • Deleting Salesforce files isn't available over MCP — use File Explorer in the web UI.
  • You'll only be offered scopes that actually do something. If the scope list looks shorter than this guide suggests, that's why.

Never, by design

  • Connecting a new Salesforce org. That needs a browser OAuth sign-in.
  • Anything your Salesforce user can't do. Calls run as the user who authorised the org, so their profile and sharing rules still apply. Managed and protected metadata stays hidden.
  • Anything your workspace role can't do. Record changes need owner/admin; a read-only member holding a data:write token still can't write.
  • Writing when your deployment forbids it. Record changes also require writes to be enabled server-wide, and are restricted to sandboxes unless an operator has explicitly allowed production.
  • Platform administration. Impersonating users, exporting or restoring the database are not exposed to AI clients. One bad tool call there would be a whole-platform problem, so they stay in the web UI.
  • Non-SELECT SOQL, and reading your AI provider key, anyone's password, or any stored Salesforce token.

It also can't see an org it hasn't pulled

Search and some field-level detail cover metadata already pulled into orgadmin.ai. On a freshly connected org, run a pull first (see Metadata explorer) or an empty result may look like an empty org.

Security & what a connection can reach

  • A connection acts as you. Anyone holding its credential has your granted scopes across every org in your workspace. Credentials are stored only as SHA-256 hashes.
  • Signing in keeps secrets out of your hands. When you connect by URL, the app receives a short-lived access token (an hour) and a refresh token that is replaced every time it is used, so nothing long-lived is ever copied, pasted or saved in a file. Codes are bound to the app that asked for them with PKCE, and can be used once.
  • Check the consent screen. Any app can ask to connect, but only you can say yes. The screen names the site you'll be sent back to — if that isn't the app you just clicked Connect in, cancel.
  • Disconnecting and revoking are instant. Every single call re-checks the credential, so disconnecting an app or revoking a token cuts it off mid-conversation. Deactivating an account does the same to all of its connections and tokens.
  • Everything is audited. Each call is recorded with the tool, the arguments, the org it touched, the app or token that made it, and whether it succeeded — alongside the audit trail from the web UI.
  • You can read that trail yourself. Usage has an MCP activity log: every client that connected, which connection it used, every tool call with its arguments and how long it took, and anything that failed. Check it if a token has been on a shared machine, or when you want to know what your assistant actually did.
  • Destructive tools are flagged so your client asks before running them.

Read those confirmation prompts

Field descriptions, Apex comments, flow names and debug-log bodies all flow into the AI's context, and anyone who can edit your org's metadata can put text there. That text is data, not instructions — the tools tell the AI to treat it that way — but the confirmation prompt before a record change is the thing that actually protects you. If a change you didn't ask for appears, decline it. Granting only org:readremoves this concern entirely.

Troubleshooting

  • “Tool not found” for something this guide lists — the connection lacks that scope, so the tool was never offered. Scopes are fixed when you click Allow or create a token: reconnect the app and tick it, or make a new token. Run whoami to see what you have.
  • The app keeps asking you to sign in again — the connection was disconnected in Settings, replaced by connecting the same app again, or left unused for 90 days. Sign in once more and it carries on.
  • 401 / “Unknown or revoked token” with a personal token — the token is wrong, revoked, expired, or the account was deactivated. All four look identical on purpose, so the endpoint can't be used to fish for valid tokens. Create a fresh token.
  • 404 on the endpoint — MCP is switched off for this deployment.
  • Anything client-specific — a connection that fails at startup, a client that connects but lists no tools, an extension that installs but can't call anything: those live in Connect ChatGPT, Claude, Claude Code & Codex, sorted by symptom.
  • “This connection is read-only for …” — you set that org to read only for this app or token. Change it with Orgs on its row in Settings → MCP access. An org you set to Off doesn't appear in list_orgs at all.
  • “Data writes are disabled on this server” — an operator setting, not something you can work around from the client.
  • “Restricted to sandbox orgs” — you aimed a record change at production and this deployment only permits sandbox writes.
  • “matches more than one org” — two orgs match the name you used. It refuses to guess rather than risk the wrong org; pass the exact orgId from list_orgs, or rename an org in Settings.
  • A result was “too large to return” — ask for less: filter the list, request fewer components, or add a LIMIT. Profiles especially are huge — read one at a time.
  • A big file won't write, or a read comes back cut off — the ceiling here is your AI client's, not ours. A single reply can only carry so much, so a tool call that tries to send a few thousand lines at once is truncated before it arrives, and a result that big is trimmed before your assistant reads it. The tools are built for this: ask it to search the project for the line it needs, read a range rather than the whole file, and write a long file in parts. If your assistant tries the same oversized call twice, say so — that phrasing is usually enough. In Claude Code you can also raise MAX_MCP_OUTPUT_TOKENS to let bigger results through.
  • Rate limited — there's a per-token ceiling on tool calls per minute. Wait a moment and continue.

Follow along in your own org

This guide sets up MCP Server. 14-day free trial, no credit card.

Start free trial