Zavia for developers

MCP documentation

Connect your AI tools to company search and ownership evidence. Set up your client, choose its permissions and test the connection.

Create an API key

Streamable HTTP

Give your agent access to ownership evidence.

Connect with a Zavia API key. Each request uses that key’s workspace, permissions and remaining allowance.

Create an API key

MCP server URL

https://connect.zavia.ai/mcp

Connect your client

API key · remote connector

Connect Claude to Zavia

1
In Claude, open Customize → Connectors → Add custom connector. Name it Zavia and paste the server URL below.
2
Choose “No sign in” under Authentication. In Request headers, add Authorization with the value Bearer YOUR_ZAVIA_API_KEY. Use a read-only key to test the connection.
3
Add and enable the connector in your conversation. Ask “Check my Zavia usage” to verify access without running an investigation.

Official Claude setup guide

Zavia MCP server URL

https://connect.zavia.ai/mcp

Authentication header

Authorization: Bearer YOUR_ZAVIA_API_KEY

Create your key in Dashboard → API keys. Enter it in your client’s credential settings, never in a chat message. Workspace administrators may need to allow custom connectors.

Managed sign-in · workspace access required

Connect your approved ChatGPT workspace

1
Use a ChatGPT account with access to this Zavia Site. This managed connection is separate from the self-service API-key endpoint.
2
Open ChatGPT Plugins, choose Add custom MCP server, and paste the managed URL below. Select OAuth, complete sign-in, then review and install the discovered tools.
3
Enable Zavia in your conversation and ask “Check my Zavia usage”. If you need workspace access, contact us using the link below.

Official ChatGPT setup guide

Managed ChatGPT MCP URL

https://zavia-homepage-redesign.sens663.chatgpt.site/mcp

Use the managed connection

ChatGPT cannot send your Zavia API key as a custom header. The managed URL uses sign-in and Site access permissions. Creating a free Zavia account does not automatically grant access to this connection.

Request ChatGPT access

API key · Streamable HTTP

Connect Gemini CLI

1
Create a Zavia API key, then open your user configuration at ~/.gemini/settings.json.
2
Merge the configuration below into the file. Replace YOUR_ZAVIA_API_KEY locally with your key. Keep this file out of version control.
3
Restart Gemini CLI and run /mcp to check the connection. Ask “Check my Zavia usage”. This setup is for Gemini CLI, not the consumer Gemini chat app.

Official Gemini setup guide

Zavia MCP server URL

https://connect.zavia.ai/mcp

~/.gemini/settings.json

{
  "mcpServers": {
    "zavia": {
      "httpUrl": "https://connect.zavia.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ZAVIA_API_KEY"
      }
    }
  }
}

Create your key in Dashboard → API keys. Enter it in your client’s credential settings, never in a chat message. Workspace administrators may need to allow custom connectors.

API key · MCP tool

Add Zavia to a Copilot Studio agent

1
Open your agent in Copilot Studio. Go to Tools → Add a tool → New tool → Model Context Protocol.
2
Name the server Zavia and paste the URL below. Choose API key authentication, Type: Header, and header name: Authorization.
3
Create a connection with Bearer YOUR_ZAVIA_API_KEY as the credential value. Add the server to your agent and test “Check my Zavia usage”. This uses Copilot Studio; it is not a paste-in connection for consumer Copilot chat.

Official Copilot setup guide

Zavia MCP server URL

https://connect.zavia.ai/mcp

Authentication header

Authorization: Bearer YOUR_ZAVIA_API_KEY

Create your key in Dashboard → API keys. Enter it in your client’s credential settings, never in a chat message. Workspace administrators may need to allow custom connectors.

API key · MCP configuration

Connect Cursor

1
Set ZAVIA_API_KEY in the environment used to launch Cursor.
2
Merge the JSON below into .cursor/mcp.json in your project. The key is read from the environment rather than committed in the file.
3
Open Cursor’s MCP settings, enable Zavia and check its tools. Ask the agent “Check my Zavia usage”.

Official Cursor setup guide

Zavia MCP server URL

https://connect.zavia.ai/mcp

.cursor/mcp.json

{
  "mcpServers": {
    "zavia": {
      "url": "https://connect.zavia.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ZAVIA_API_KEY}"
      }
    }
  }
}

Create your key in Dashboard → API keys. Enter it in your client’s credential settings, never in a chat message. Workspace administrators may need to allow custom connectors.

Test your connection

This checks authentication and workspace usage without starting a report.

API key

Building your own MCP client?

Send a descriptive User-Agent header, such as YourApp/1.0. Cloudflare can reject default library identifiers such as Python urllib with error 1010. Keep your Zavia API key in the Authorization: Bearer header.

Available tools

A read-only key lists 4 tools. Investigation access adds the ownership investigation tool.

Search companies

Read

zavia_search_companies

Resolve a company by legal name, registration number or VAT number and country. Search first and ask the user to select when more than one company matches. Uses the workspace API search allowance.

Investigate company ownership

Uses report allowance

zavia_investigate_company

Start, resume or cancel an ownership investigation for a confirmed company ID from search. Starting a new report may consume one shared investigation credit. Generate a UUID runId once and reuse the same runId and settings for retries. If processing, wait retryAfterSeconds and call again with resume:true. Never invent owners, missing evidence or company IDs.

List saved investigations

Read

zavia_list_investigations

List recent saved investigations in the authenticated workspace. Does not consume an investigation credit.

Read saved ownership evidence

Read

zavia_get_investigation

Read a saved ownership report by case ID, including sources, ownership paths, calculations and evidence gaps. Only the authenticated workspace is accessible. Does not consume another investigation credit.

Check workspace usage

Read

zavia_get_usage

Check remaining investigation and API search allowances and reset times. This is also a connection check; it does not fetch company data or consume an investigation credit.

Start with a connection check

Ask your agent “Check my Zavia usage.” This checks the connection without fetching company data or using an investigation credit. Confirm the company before asking it to start an investigation.

When a report is processing, the agent receives a run ID and retry delay. Resuming the same run avoids creating a second investigation.

Read the MCP reference →