Skip to content
Help Center

Connect AI agents to Persona with MCP

Last updated on .

View Markdown Contact support Contact support 8 min read
On this page

Overview

The Persona MCP Server lets AI assistants and agents, such as Claude and ChatGPT, work with your Persona data. MCP (Model Context Protocol) is an open standard that lets AI tools call other services.

There are two versions of the Persona MCP Server:

  • MCP Server V2 (latest). We recommend V2. You sign in with your Persona Dashboard account, so you do not need an API key. An agent that runs with no person to sign in can use a machine client. The assistant can read your Persona records and make a small set of changes, with your own Dashboard role.
  • MCP Server V1. V1 connects with a Persona API key and makes every action in the Persona API available to your agent. Use V1 only if you need something that V2 does not do.

Which version should I use?

Start with V2. Use V1 only if one of these is true:

  • Your agent must connect with an API key.
  • Your agent needs an action that V2 does not have, such as editing templates or managing webhooks. A machine client token does not work on the Persona REST API, so use V1 if your agent also calls that API.

If your agent runs with no person to sign in, you can use V2 with a machine client. For more information, see Connect a machine client to Persona with OAuth.

MCP Server V2 (latest)MCP Server V1
Server URLhttps://withpersona.com/mcphttps://mcp.withpersona.com
How you connectEach person signs in with their Dashboard account, or an unattended agent uses a machine clientA Persona API key
What it can doRead records, plus a small set of changesEvery action in the Persona API
Whose access it usesYour own Dashboard roleThe permissions of the API key
Best forClaude, ChatGPT, and other AI appsAgents and developer tools

When you give an AI tool access to Persona data, make sure that this agrees with your organization’s security and compliance requirements. Your business decides its own risk tolerance and how it uses Persona.

MCP Server V2 (latest)

MCP Server V2 is at https://withpersona.com/mcp. You connect it to Claude or ChatGPT as a custom connector. Other AI apps can connect if they support OAuth sign-in for MCP servers.

Connect Claude or ChatGPT

  1. In Claude or ChatGPT, open the connector settings and add a custom connector.
  2. Enter the server URL https://withpersona.com/mcp.
  3. Select Connect. Claude or ChatGPT opens a Persona sign-in page.
  4. Sign in with your Persona Dashboard account. Your organization’s usual login rules, such as SSO and MFA, apply.
  5. On the Persona consent screen, check which organization and access the app asks for, then approve.

At first, the connector can only read data. The first time you ask the assistant to make a change, you approve write access on the Persona consent screen. Depending on the app, you might need to reconnect Persona to see that screen.

If you cannot connect, contact your Persona account team or Persona support.

What the assistant can read

The assistant can search, fetch, and list the records that you can see in the Dashboard. These include:

  • Inquiries and Inquiry Templates
  • Accounts
  • Cases
  • Verifications
  • Reports
  • Transactions
  • Workflows
  • Lists

It can also list your environments. Some records, such as Inquiries, belong to one environment. Ask the assistant to list your environments first, then tell it whether you mean production or sandbox.

What the assistant can change

After you approve write access, the assistant can:

  • Create an Inquiry from an Inquiry Template, with a one-time link if you ask for one
  • Add a comment to a Case
  • Add a tag to a Case, or remove a tag
  • Set the status of a Case
  • Assign or unassign a Case
  • Approve or decline an Inquiry

The assistant cannot delete anything. It can make up to 20 changes per minute.

Approving or declining an Inquiry changes the outcome for your end user and triggers your webhooks and Workflows. You cannot undo it through the assistant. Anyone who has a one-time link can complete the Inquiry, so share the link only with the intended person.

Permissions and access

  • The assistant uses your own Dashboard role. It can see and change only what you can see and change in the Dashboard. For example, to approve or decline an Inquiry, you need permission to decide Inquiries for that template.
  • The assistant can access only the organization that you approved on the consent screen.
  • Claude and ChatGPT ask you to confirm before they make a change.
  • Persona records each change in your organization’s audit log, under your name.

Example prompts

  • “List my Persona environments.”
  • “Show my 5 most recent inquiries in sandbox.”
  • “Summarize the verifications on inquiry inq_….”
  • “Search for the account for jane@example.com.”
  • “Add the comment ‘Documents checked’ to case case_… and set its status to Resolved.”
  • “Create an inquiry from template itmpl_… in sandbox and give me a one-time link.”

Disconnect

To disconnect Persona, remove the connector in the Claude or ChatGPT connector settings. After that, the assistant cannot use your Persona access.

Data handling

Persona sends the data that the assistant asks for to the AI provider. The provider’s terms control how it handles that data. Read those terms before you connect. To learn how Persona handles data, read the Persona privacy policy.

MCP Server V1

MCP Server V1 at https://mcp.withpersona.com makes every action in the Persona API available to your agent as a tool. It uses the same API keys that you manage in the Dashboard.

What you can build

  • Data checks. An agent compares fraud signals, Reports, or Inquiry results in Persona with the data in your own systems.
  • Help for manual review. An internal assistant reads Cases, Accounts, and Verifications and summarizes them for your reviewers. Persona also has Case Review Agents built into Cases. Use the MCP Server if you want Persona data in your own AI tools.
  • Reporting. An agent pulls data from Reports or Inquiries and formats it.
  • Development. Your engineers use an AI coding assistant to test endpoints, update templates, and prototype Workflows.

Connect

  1. In the Dashboard, create an API key for the agent. Give the key only the permissions that the agent needs. For more information, see API Keys.
  2. In your AI tool or agent, add an MCP server with the URL https://mcp.withpersona.com.
  3. Send the API key in one of these headers:
    • Authorization: Bearer <your-key>
    • x-api-key: <your-key>

The agent sees every Persona API action as a tool, but it can do only what the key permits. If it tries something outside the key’s permissions, the Persona API returns a permission error. This is why we recommend one key for each agent, with the fewest permissions possible. If the agent only reads data, use a read-only key.

To use Persona in Claude or ChatGPT, we recommend MCP Server V2. If you must use V1 in Claude, ChatGPT, or Grok, follow these steps.

Claude

In Claude’s connector settings, add a custom connector. Custom connectors usually use OAuth. An organization admin can use the beta static header option to send the API key in an Authorization or x-api-key header for the whole organization. If you use the Anthropic Messages API, put the API key in the authorization_token field of the mcp_servers configuration.

ChatGPT

Turn on Developer Mode. On Business and Enterprise workspaces, an admin might first need to allow custom MCP connectors. Then add a custom connector in ChatGPT’s connector settings and select API key as the authentication type. If you use the OpenAI Responses API, put the API key in the authorization field of the mcp tool.

Grok

In Grok’s connector settings, add a custom connector, enter the server URL, and enter your API key. If you use the xAI API, put the API key in the authorization field of the remote MCP tool, or use the headers field for a different header name.

Tips for reliable results

  • Give exact IDs. Say “create an Inquiry from template itmpl_…”, not “create an inquiry”.
  • Page through lists on purpose. Most list actions return one page of results. Tell the agent to fetch the next page with the cursor from the last result.
  • Pin an API version. Send the Persona-Version header, for example Persona-Version: 2026-09-29, so that results do not change when Persona releases a new version. If you do not send it, the server uses its default version.
  • Pass data between steps. The server does not keep a session or remember earlier requests. If your agent fetches an Inquiry and then a related Verification, your agent must pass the IDs from the first result to the second request.

Rate limits and errors

MCP Server V1 uses the same rate limits as the Persona API. If the agent exceeds a limit, it gets a 429 error. Wait and try again, with more time between each attempt.

Was this page helpful?If something is missing, let us know and we will take a look.
Thanks for the feedback. It helps us improve these docs.