Copy page

Getting Started

Connect ContactLevel to Claude or Codex

Use ContactLevel from your AI assistant to search contacts, companies, audiences, website visits, and LinkedIn analytics. You can also allow actions such as creating audiences and running syncs.

MCP server URL:

Code
https://a.contactlevel.com/mcp

You need a ContactLevel account and membership in an organization with public API access through an active plan or eligible trial.

Sign in and choose permissions

Dashboard sign-in is the recommended way to connect. You do not need to copy an API key or provide an OAuth client ID or secret.

When your assistant opens ContactLevel:

1. Sign in with your normal ContactLevel account.
2. Search for and select the organization you want to connect.
3. Choose Read only or Read & write.
4. Click Approve access and return to your assistant.

Permission	What the connection can do
Read only — default	Search and retrieve existing data, analytics, balances, and statuses. Cannot create or update records, start exports, change audience membership, or run syncs.
Read & write	Access the same data and run create/update, export, and sync actions. Chargeable actions use your organization's credits.

Each connection is limited to the organization and permission you approve. ContactLevel enforces permissions on the server; read-only connections do not expose action tools.

Claude web or desktop

No CLI installation is needed for this option.

1. Open Settings → Connectors and choose Add custom connector. Your workspace administrator may need to enable or add custom connectors first.
2. Name it ContactLevel and enter https://a.contactlevel.com/mcp as the remote MCP server URL.
3. Leave the advanced OAuth Client ID and OAuth Client Secret fields empty.
4. Add the connector and click Connect.
5. Complete the ContactLevel sign-in and approval steps above.
6. Enable the connector's tools in your conversation.

See Claude's custom connector guide for client-specific settings and availability.

Claude Code

With the Claude Code CLI installed, run:

Code
claude mcp add --transport http --scope user contactlevel https://a.contactlevel.com/mcp

Adding the server saves its configuration but does not automatically open authentication. Next, run:

Code
claude mcp login contactlevel

Complete the ContactLevel sign-in and approval flow in your browser. If the add command says the server already exists, skip adding it again and run the login command.

If your Claude Code version does not support mcp login, run claude, enter /mcp, select contactlevel, and choose Authenticate.

The user scope makes this connection available across your projects. See the Claude Code MCP guide for other configuration options.

Codex

With the Codex CLI installed, run:

Code
codex mcp add contactlevel --url https://a.contactlevel.com/mcp

If the command opens the sign-in flow, complete it once. If authentication has not started, run:

Code
codex mcp login contactlevel

Sign in to ContactLevel, select your organization and permission, and approve. Once Codex reports success, you do not need to run login again.

Check the configured connection with:

Code
codex mcp list

You can also configure the connection in your personal ~/.codex/config.toml and then run the login command:

Code
[mcp_servers.contactlevel]
url = "https://a.contactlevel.com/mcp"

See the official Codex MCP guide for app and IDE configuration.

Verify your connection

Ask your assistant:

Use ContactLevel's getOrganizationId tool and tell me the connected organization name, ID, and permission before doing anything else.

The existing organization tool returns:

Code
{
  "organization_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "organization_name": "Acme Inc",
  "permission": "read_only"
}

Then try a read:

Show my ContactLevel credit balance.

Search my ContactLevel contacts and return the first 10 results.

Show my LinkedIn campaigns for the previous complete month, sorted by impressions.

For actions, use a Read & write connection and specify the intended organization. For example:

Confirm that ContactLevel is connected to Acme Inc, then ask me before creating an audience named Q4 Prospects.

Optional: connect with an API key

CLI clients can use an existing ContactLevel API key instead of dashboard sign-in. Direct API-key connections have read/write access. Use dashboard sign-in if you want a read-only connection.

Claude Code

Code
claude mcp add --transport http --scope user contactlevel-key https://a.contactlevel.com/mcp \
  --header "X-Api-Key: api_YOUR_KEY"

Codex

Add this to your personal ~/.codex/config.toml:

Code
[mcp_servers.contactlevel-key]
url = "https://a.contactlevel.com/mcp"
http_headers = { "X-Api-Key" = "api_YOUR_KEY" }

Replace api_YOUR_KEY with your actual key. Keep it out of shared files, Git, and screenshots. No OAuth login is needed for these key-based connections. Do not combine an API-key header and an OAuth login on the same connection.

Multiple organizations and reconnecting

One connection authorizes one organization. To use multiple organizations, configure separately named connections, such as contactlevel-acme and contactlevel-internal, and approve each for the intended org. Check getOrganizationId on the connection you are about to use; its name alone does not prove which org is authorized.

ContactLevel reuses your organization's active MCP-KEY in Developers, creating one if needed. Each approval gets separate OAuth credentials and permissions. Reconnecting does not automatically revoke earlier grants.

To change an OAuth connection's organization or permission, authenticate again and choose the new settings. Reconnect or restart your client so it loads the new login. Older grants retain their previously approved access until they expire or are revoked.

Deleting MCP-KEY invalidates all connections using that key. Removing a connection from your assistant stops that client from using it, but does not necessarily revoke its server-side authorization.

Troubleshooting

Issue	What to do
codex: command not found or claude: command not found	Install the corresponding CLI before using terminal instructions, or use the app's connector settings.
The browser ends at 127.0.0.1 or localhost	This is expected for CLI OAuth. The client receives the authorization code on your computer and finishes login. Its final page may be plain text; check the client for successful authentication.
The browser opens authentication a second time	If adding the server already completed authentication, do not immediately run another login command.
The approval request expired or was already used	Start a fresh login from your assistant instead of reusing the browser URL.
Actions are missing or return 403 insufficient_permission	The connection is read-only. Reconnect and explicitly approve Read & write if you need actions.
The wrong organization is shown	Check getOrganizationId, then use the correct connection or authenticate again with the intended org.
The organization cannot be selected for approval	Confirm your membership and that the organization has an active plan or eligible trial for public API access.
A request is rate-limited	Wait for the retry interval returned by the server.
A write timed out or its response was lost	Check whether it completed before trying again. Do not automatically repeat the action.

For individual endpoints and request parameters, see the API Reference.