Quickstart: MCP server

Connect the Jell MCP server to Claude Code, claude.ai, ChatGPT, Cursor, VS Code or your own agent on the Claude or OpenAI API: SERP, backlink and keyword data, B2B contact and company enrichment, social scraping and outbound as native tools on one balance.

Jell speaks the Model Context Protocol (MCP): connect once and your agent gets the discover, inspect, run loop as native tools, with the spending rules delivered in the handshake. Nothing to install.

https://api.jell.run/mcp

• Transport: Streamable HTTP, stateless. Every request is one POST answered with one JSON response: no session to keep alive, no stream to hold open.
• Sign-in: OAuth (sign in once in the browser and approve a workspace) or an API key sent as Authorization: Bearer rg_live_.... Both reach the same workspace, wallet and error codes.
• Tools: ten, listed under The tools.

Pick your setup

• claude.ai, Claude Desktop, Claude mobile: custom connector, OAuth.
• ChatGPT: developer mode, OAuth.
• Mistral Vibe (Le Chat), Perplexity, Manus: other chat apps, OAuth or key.
• Claude Code: claude mcp add, OAuth or key.
• Codex: codex mcp add, OAuth or key.
• Cursor, VS Code, Gemini CLI, Cline, Zed, Devin Desktop (Windsurf), Goose, Kiro, JetBrains, Warp: IDE and CLI clients, OAuth or key.
• Your own agent on the Claude API, Claude Managed Agents or the Claude Agent SDK: Claude platform, key.
• Your own agent on the OpenAI API or the OpenAI Agents SDK: OpenAI platform, key.
• LangChain, LangGraph, Vercel AI SDK, Google ADK, LlamaIndex, CrewAI, Mastra: agent frameworks, key.
• n8n, Make, Zapier, Microsoft Copilot Studio, Dify and other no-code builders: no-code builders, key or OAuth.
• A client that only starts local (stdio) servers: mcp-remote bridge, key or OAuth.
• Anything else: any MCP client, key.

Not sure where the agent will run? Use a key: every MCP client that can send a header works with it. Then test the connection from the machine or platform the agent runs on.

Before you connect

1. Sign in on the dashboard with Google, GitHub, a password or an emailed code. A new workspace starts with promotional credit.
2. For a key-based setup, create a key under API keys. Use a live key (rg_live_...) for real data: a test key (rg_test_...) returns clearly labeled simulated data.
3. Keep the key in your platform's secret store or an environment variable, never in a committed file.

OAuth setups need none of this ahead of time: the sign-in page creates the workspace on the first connection.

Chat apps

claude.ai, Claude Desktop and Claude mobile

1. Open Customize → Connectors, select + and choose Add custom connector.
2. Name it Jell, paste https://api.jell.run/mcp as the URL and add it.
3. Select Connect, sign in on the Jell page (password, Google, GitHub or an emailed code) and approve the workspace.
4. In a chat, turn Jell on from the tools menu and ask Claude to check your Jell balance. That call is free.

On Team and Enterprise plans, an Owner adds the connector first under Organization settings → Connectors → Add → Custom → Web; members then select Connect under Customize → Connectors and sign in with their own Jell account. The Free plan allows one custom connector. A connector added on claude.ai also appears in Claude Desktop and the mobile apps. Approving grants one scope, mcp: the tools and the balance of the workspace you picked, nothing else.

Organizations with the request headers beta can pick No sign-in and add the header authorization with the value Bearer rg_live_... instead; everyone in the organization then shares that key's workspace.

ChatGPT

ChatGPT connects over OAuth only: it cannot send an API key.

1. Open Settings → Security and login and turn on Developer mode. It is on the web for Plus, Pro, Business, Enterprise and Edu; on Business, Enterprise and Edu a workspace admin enables it first.
2. Go to Plugins, select +, and name the plugin Jell.
3. Under Connection, enter https://api.jell.run/mcp, choose OAuth, and create it.
4. Sign in on the Jell page and approve the workspace whose tools and balance you want to use.
5. In a new chat, open the + menu, choose Developer mode, select Jell, and ask it to check your balance.

ChatGPT asks you to confirm each call to a tool that can spend (run, batch_run, watch); the free read tools run without asking. The connection carries over to later chats, where you select it again. OpenAI's connection guide has the current screens.

Other chat apps

• Mistral Vibe (formerly Le Chat): Connectors → + Add Connector → Custom MCP Connector, name Jell, the URL, then Connect and sign in with OAuth. Only an admin can add connectors.
• Perplexity: Settings → Connectors → + Custom connector → Remote, the URL, Streamable HTTP, and API Key authentication with your key. Prefer the key: Perplexity's OAuth option is reported to fail with servers that issue no client secret, as Jell does.
• Manus: Settings → Integrations → Custom MCP Servers, the URL, and your key as the bearer token.

Coding agents

Claude Code

claude mcp add --transport http jell https://api.jell.run/mcp

Then sign in: type /mcp inside Claude Code, pick jell and choose Authenticate (recent versions also take claude mcp login jell from the shell). Your browser opens the Jell consent page; approve the workspace and Claude Code stores the token and refreshes it on its own. Add --scope project to share the server through .mcp.json: each teammate signs in with their own account, so nothing secret lands in the file.

With a key instead (CI, a headless box, a script):

claude mcp add --transport http jell https://api.jell.run/mcp \
  --header "Authorization: Bearer rg_live_..."

In a shared .mcp.json, reference an environment variable instead of pasting the key: "headers": {"Authorization": "Bearer ${JELL_API_KEY}"}. Claude Code never offers OAuth for a server that already sends an Authorization header, so remove the header to switch back.

Codex

codex mcp add jell --url https://api.jell.run/mcp

Codex finds the OAuth server and opens the consent page right away; codex mcp login jell signs in again later, and codex mcp list shows whether the server is authenticated. The CLI and the IDE extension share ~/.codex/config.toml.

With a key instead, keep the bare key (no Bearer prefix) in an environment variable; Codex reads it at start, so the config file never holds it:

export JELL_API_KEY=rg_live_...
codex mcp add jell --url https://api.jell.run/mcp --bearer-token-env-var JELL_API_KEY

IDE and CLI clients

Every client names its fields differently, so copy the block for yours. Where OAuth is supported, leave out the header: the client finds the Jell sign-in page by itself.

Cursor: .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. Without headers, Cursor signs in through the browser.

{
  "mcpServers": {
    "jell": {
      "url": "https://api.jell.run/mcp",
      "headers": {"Authorization": "Bearer ${env:JELL_API_KEY}"}
    }
  }
}

VS Code and GitHub Copilot: .vscode/mcp.json. The servers live under servers and need "type": "http". VS Code asks for the key once and stores it; without headers and inputs, it registers itself and opens the Jell sign-in page instead.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jell-key",
      "description": "Jell API key",
      "password": true
    }
  ],
  "servers": {
    "jell": {
      "type": "http",
      "url": "https://api.jell.run/mcp",
      "headers": {"Authorization": "Bearer ${input:jell-key}"}
    }
  }
}

Gemini CLI: add the server, then run /mcp auth jell inside Gemini CLI to sign in. For a key, add -H "Authorization: Bearer rg_live_..." to the command. Add -s user to register it for every project instead of the current one.

gemini mcp add -t http jell https://api.jell.run/mcp

Cline: MCP Servers → Configure → Configure MCP Servers. Cline needs "type": "streamableHttp": it rejects "http", and without a type it falls back to the old SSE transport, which Jell does not serve.

{
  "mcpServers": {
    "jell": {
      "type": "streamableHttp",
      "url": "https://api.jell.run/mcp",
      "headers": {"Authorization": "Bearer rg_live_..."}
    }
  }
}

Zed: settings.json, or Settings → AI → MCP Servers → Add Remote Server. The key is context_servers, not mcpServers; without headers, Zed signs in with OAuth.

{
  "context_servers": {
    "jell": {
      "url": "https://api.jell.run/mcp",
      "headers": {"Authorization": "Bearer rg_live_..."}
    }
  }
}

Other clients:

Clients that only start local servers

Some clients can only launch a local (stdio) server, for example claude_desktop_config.json in Claude Desktop or JetBrains AI Assistant. Bridge them with mcp-remote, which runs locally and forwards to Jell:

{
  "mcpServers": {
    "jell": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://api.jell.run/mcp",
               "--header", "Authorization:${RG_AUTH}"],
      "env": {"RG_AUTH": "Bearer rg_live_..."}
    }
  }
}

Keep Authorization:${RG_AUTH} without a space: some clients split arguments on spaces. Leave out the two --header arguments to sign in with OAuth instead; mcp-remote opens the browser and keeps the token in ~/.mcp-auth. In Claude Desktop, the Connectors setup is simpler; use the bridge only when a local config is required.

Your own agent

For an agent you run in code, pass the key from your secret store. None of these need a browser.

Claude API

The Messages API connects to MCP servers for you (beta header mcp-client-2025-11-20). Pass the key as authorization_token, and reference the server from an mcp_toolset:

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.jell.run/mcp",
        "name": "jell",
        "authorization_token": os.environ["JELL_API_KEY"],
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "jell"}],
    messages=[{"role": "user", "content": "Check my Jell balance."}],
)

The connector runs on the Claude API, Claude Platform on AWS and Microsoft Foundry. On Amazon Bedrock and Google Vertex AI, run an MCP client yourself, as in agent frameworks.

Claude Managed Agents

Declare the server on the agent (no credential there), then store the key in a vault as a static_bearer credential for the same URL and attach the vault when you start a session:

agent = client.beta.agents.create(
    name="GTM research",
    model="claude-opus-5",
    mcp_servers=[{"type": "url", "name": "jell", "url": "https://api.jell.run/mcp"}],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "jell"}],
)
vault = client.beta.vaults.create(display_name="Jell")
client.beta.vaults.credentials.create(
    vault_id=vault.id,
    display_name="Jell API key",
    auth={"type": "static_bearer", "mcp_server_url": "https://api.jell.run/mcp",
          "token": os.environ["JELL_API_KEY"]},
)
session = client.beta.sessions.create(agent=agent.id, environment_id=environment.id, vault_ids=[vault.id])

MCP tools ask for approval before each call by default (always_ask); set a permission policy on the toolset to change that. On an environment with limited networking, set allow_mcp_servers: true or the agent cannot reach the server.

Claude Agent SDK

import asyncio
import os
from claude_agent_sdk import ClaudeAgentOptions, query

options = ClaudeAgentOptions(
    mcp_servers={
        "jell": {
            "type": "http",
            "url": "https://api.jell.run/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['JELL_API_KEY']}"},
        }
    },
    allowed_tools=["mcp__jell__*"],
)


async def main():
    async for message in query(prompt="Check my Jell balance.", options=options):
        print(message)

asyncio.run(main())

The SDK does not run the OAuth flow, so pass the key in headers. allowed_tools lets the agent call every Jell tool without asking; list single tools (mcp__jell__discover, mcp__jell__inspect, ...) to keep paid calls behind a permission check.

OpenAI Responses API and Agents SDK

The Responses API calls the server from OpenAI's side. Send the key in headers on every request (OpenAI does not store it):

import os
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "jell",
        "server_url": "https://api.jell.run/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['JELL_API_KEY']}"},
        "require_approval": "never",
    }],
    input="Check my Jell balance.",
)

With the OpenAI Agents SDK, the connection runs in your process. Raise client_session_timeout_seconds: its default of 5 seconds cuts off any paid run that takes longer.

import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main():
    async with MCPServerStreamableHttp(
        name="jell",
        params={
            "url": "https://api.jell.run/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['JELL_API_KEY']}"},
            "timeout": 30,
        },
        client_session_timeout_seconds=120,
        cache_tools_list=True,
    ) as jell:
        agent = Agent(name="GTM research", mcp_servers=[jell])
        result = await Runner.run(agent, "Check my Jell balance.")
        print(result.final_output)

asyncio.run(main())

Agent frameworks

LangChain and LangGraph (pip install "langchain[mcp]"):

import os
from fastmcp.client import Client
from langchain.mcp import MCPAdapter

async with MCPAdapter(Client("https://api.jell.run/mcp",
                             auth=os.environ["JELL_API_KEY"])) as jell:
    tools = await jell.list_tools()
    # pass tools to create_agent(...) and run the agent inside this block

On the older langchain-mcp-adapters, use MultiServerMCPClient({"jell": {"transport": "http", "url": "https://api.jell.run/mcp", "headers": {"Authorization": "Bearer rg_live_..."}}}).

Vercel AI SDK:

import { createMCPClient } from "@ai-sdk/mcp";

const jell = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.jell.run/mcp",
    headers: { Authorization: `Bearer ${process.env.JELL_API_KEY}` },
  },
});
const tools = await jell.tools();

Google ADK:

import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

jell = McpToolset(connection_params=StreamableHTTPConnectionParams(
    url="https://api.jell.run/mcp",
    headers={"Authorization": f"Bearer {os.environ['JELL_API_KEY']}"},
    timeout=30,
    sse_read_timeout=300,
))
# any Gemini model works here
agent = LlmAgent(model="gemini-2.5-flash", name="gtm_research", tools=[jell])

More frameworks, same URL and header:

Any official MCP SDK: the TypeScript and Python SDKs connect with their Streamable HTTP client transport and an Authorization header. Both also run the full OAuth flow when you give them an OAuth provider.

No-code agent builders

n8n: add an MCP Client Tool to your AI Agent node. Set the endpoint to https://api.jell.run/mcp, the transport to HTTP Streamable, and authentication to Bearer Auth with your key (or MCP OAuth2, which registers itself, on n8n 1.119 and later). The node gives a call 60 seconds by default.

Microsoft Copilot Studio: in your agent, Tools → Add a tool → New tool → Model Context Protocol. Enter the server URL, then pick OAuth 2.0 → Dynamic discovery, or API key as a header named Authorization with the value Bearer rg_live_.... The Manual OAuth mode needs a client secret, which Jell does not issue.

Make: the MCP Client app, + new MCP server, the URL, and your key as the API key or access token.

Zapier: an MCP Client connection with the URL, the Streamable HTTP transport, OAuth off, and your key as the bearer token.

Dify: Integrations → Tools → MCP → Add MCP Server (HTTP), the URL, and an Authorization header with Bearer rg_live_.... Keep the server identifier once saved.

Flowise, Relevance AI, Lindy and similar builders: choose Streamable HTTP (sometimes just "HTTP"), the URL, and a bearer token or Authorization header with your key. A builder that only offers SSE cannot connect.

Any other MCP client

Give the client these settings:

• URL: https://api.jell.run/mcp
• Transport: Streamable HTTP (labeled "HTTP", http, streamable-http or streamableHttp depending on the client). Not SSE.
• Header: Authorization: Bearer rg_live_..., or OAuth if the client implements MCP authorization (discovery from the 401 challenge, dynamic client registration, PKCE).

Test the connection

Run this from the machine or platform where the agent runs. It lists the tools and spends nothing:

curl -s https://api.jell.run/mcp \
  -H "Authorization: Bearer $JELL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A JSON reply that names ten tools means the network path and the key both work. A 401 means the key is missing, mistyped, revoked or expired. For a free call end to end, send this body the same way:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"balance","arguments":{}}}

In a chat app, ask the agent to check your Jell balance.

Server details

• Endpoint: POST https://api.jell.run/mcp. GET and DELETE answer 405: there is no server stream and no session to end.
• Transport: Streamable HTTP, stateless, application/json responses. The legacy HTTP+SSE transport is not offered.
• Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Clients built for 2026-07-28 fall back to the initialize handshake on their own, as both official SDKs do.
• Capabilities: tools only. No resources, prompts or sampling.
• Key auth: Authorization: Bearer rg_live_..., or rg_test_... for simulated data.
• OAuth: OAuth 2.1 with PKCE (S256) and dynamic client registration for public clients (no client secret), one scope, mcp. Metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. Access tokens last 24 hours; refresh tokens last 90 days and rotate on every use. A platform that insists on a pre-registered client ID and secret connects with a key instead.
• Rate limit: 300 requests a minute per key or connection.
• Long runs: run and watch wait up to 25 seconds and batch_run up to 45 by default, inside the 30 to 60-second limit many clients put on a tool call. A run still going comes back with done: false: poll get_run, or repeat batch_run with the same idempotency_key to keep waiting without paying twice.
• Errors: a failing tool call comes back as a tool result with isError and the standard error envelope, so the agent can read the code and react.

How OAuth works

The flow is the same for every client, so an agent can also walk a user through it:

1. The client calls https://api.jell.run/mcp with no credentials and gets a 401 whose WWW-Authenticate header points at /.well-known/oauth-protected-resource and names the mcp scope.
2. It reads that document and /.well-known/oauth-authorization-server, registers itself at /oauth/register (RFC 7591, no pre-shared secret), and opens /oauth/authorize with a PKCE challenge and a redirect back to itself: a loopback port for terminal clients, an https callback for web clients, a custom scheme for installed apps.
3. You sign in on the consent page (password, Google, GitHub or an emailed code, the same options as the dashboard) and approve one workspace. The page names the host the browser will return to; if it is not the app you are connecting, deny.
4. The client exchanges the code at /oauth/token and receives an access token (24 hours) and a refresh token. Every later request carries the access token as a Bearer header, and the client refreshes it without asking you again.

The token grants one scope, mcp: discover, inspect and run capabilities, list runs, read history and the balance, for the approved workspace only. It cannot mint keys, change billing or invite members.

Disconnect an app

curl https://api.jell.run/v1/connected-apps \
  -H "Authorization: Bearer $JELL_API_KEY"

curl -X DELETE https://api.jell.run/v1/connected-apps/{id} \
  -H "Authorization: Bearer $JELL_API_KEY"

Disconnecting is immediate: the app's access token and its refresh token both stop working on the next call.

The tools

The tools call the same code as /v1: identical routing, billing, waterfall and error codes, with errors returned as tool results the model can read and react to.

Spending rules

The server's initialize response instructs the agent: inspect and surface the price once before a homogeneous batch, set max_cost on every item and max_total_cost on the batch, and never present sandbox (rg_test_) mock data as real. An explicit request such as “do 50” authorizes that item count within the surfaced total cap; do not ask again between items. The same rules ship in SKILL.md.

Troubleshooting

• 401 on every call: no credential, or the key is mistyped, revoked or expired. OAuth clients: reconnect to sign in again. A client with an Authorization header configured will not fall back to OAuth.
• 405 Method Not Allowed: the client is using the old SSE transport or opening a stream. Switch it to Streamable HTTP, or use the mcp-remote bridge.
• 404 Not Found: wrong host. The server is api.jell.run/mcp, not jell.run/mcp.
• A tool call times out: the client stopped waiting before the run finished. Ask for wait_seconds of 45 or less, then poll get_run; repeat a batch_run with the same idempotency_key to keep waiting without paying twice.
• 429 rate_limited: wait the number of seconds in Retry-After.
• The tools do not show up: chat apps load connectors per conversation, so start a new chat and enable Jell in the tools menu; desktop and IDE clients need a restart or a reload after a config edit.
• Results are labeled simulated: the key is a test key (rg_test_...); create a live one.
• A company network blocks the call: allow outbound HTTPS (port 443) to api.jell.run. The OAuth sign-in page is on the same host.
• The sign-in page reports a redirect mismatch: the client changed its callback address after it registered. Remove the server from the client and add it again.
• OAuth fails in a client that wants a client secret: Jell registers public clients only. Connect that client with a key.
• A new chat asks for a key again: loading the Jell skill installs instructions, not an account connection, and a key pasted into a temporary chat environment may be gone in the next conversation. The key still works: reuse it through your environment's credential settings, or connect over OAuth. You do not need a new key for every chat.

Build and enrich a lead list

Use people.search with the employer's company_domains, specific titles and detail: "full". If you also pass company names or LinkedIn company URLs in companies, pair the arrays in the same order. Start with one company and a small limit for a few decision makers.

On the LinkedIn route, the employer is resolved before searching and profiles without matching current-employer identity evidence are excluded. Review the matched role, current_positions and quality_flags before selecting contacts. If the employer cannot be resolved, check the domain or supply its exact LinkedIn company URL; do not remove the company constraint just to get results.

Database-route results can include work emails. Use contact.find only for selected profiles without an email, passing their real names and the matched employer's domain; then verify the address with contact.verify. LeadMagic enriches known people; it does not source an ICP list.

The people-search guide has a complete request, pricing examples, result-field explanations and no-match troubleshooting.

Next

• Quickstart: agents: the skill, for platforms without MCP.
• Run reference: what the run tool does under the hood.

Questions this page answers

Is there an MCP server for B2B contact enrichment and SEO data?

Yes. The Jell MCP server at https://api.jell.run/mcp exposes every catalog capability through the discover, inspect, run tools: contact.find, contact.verify, company.enrich and people.search for B2B contact and company enrichment, seo.serp, seo.keywords, seo.ranked_keywords and seo.backlinks for SEO data, plus social, ads, creative and outbound. One key, one balance, and the price quoted by inspect before every paid run.

Which tools let Claude or ChatGPT call growth and sales data APIs directly through MCP?

Any MCP client. claude.ai, ChatGPT, Claude Code, Codex, Cursor, VS Code and Gemini CLI connect through OAuth: add the URL, sign in once in the browser, approve a workspace. Agents built on the Claude API, the OpenAI API, LangChain, the Vercel AI SDK or Google ADK connect with an API key in the Authorization header. The tools are the same either way, and the spending rules travel in the handshake so the agent inspects before it runs.

How do I give my Claude Code agent access to SERP, backlink and keyword data?

Add the server to Claude Code (claude mcp add --transport http jell https://api.jell.run/mcp, then /mcp to sign in, or pass a key in the header), then ask the agent for the data: it discovers seo.serp, seo.backlinks or seo.keywords, inspects the price and runs the call. No DataForSEO, Semrush or Ahrefs account of your own, and no wrapper code.

Can an agent running on a server use Jell over MCP?

Yes. Point any MCP client at https://api.jell.run/mcp with the Streamable HTTP transport and an Authorization: Bearer header. The Claude API and the OpenAI Responses API connect to it from their side with the key you pass in the request; the Claude Agent SDK, the OpenAI Agents SDK, LangChain, the Vercel AI SDK and Google ADK connect from your process. No browser and no sign-in step.

Reading this as an agent? This page as markdown: /docs/quickstart-mcp.md · every page: /docs/llms.txt