Connect an MCP client

There are two ways to connect, and both reach the same server and the same tools:

	Sign in	API key
For	ChatGPT, Claude (claude.ai), Gemini	Claude Code, Claude Desktop config, Cursor, MCP Inspector, n8n, your own agents
Who it acts as	The person who signed in, within their role	The organisation, within the key's scopes
Records it sees	Only the records that person can see in Expedify	Every record in the organisation
Set up by	Each person, from the app	An owner or admin, in Settings → API Keys

Which address to use

Address	Use it when
`https://api.expedify.ai/v1/mcp`	You belong to one organisation, or you want to pick the organisation each time you sign in. API-key clients use this one.
`https://api.expedify.ai/v1/mcp/<org-slug>`	You belong to several organisations. Each organisation has its own address, shown in Settings → Connected Apps. Signing in through it connects that organisation directly, without an organisation picker.

ChatGPT and Claude allow only one connector per address. To use two organisations in the same app, add one connector per organisation, each with that organisation's own address.

What you'll see

You add Expedify in the app with one of the addresses above, and choose OAuth or sign-in.
The app opens Expedify. Log in if you aren't already.
The consent screen shows every permission, laid out like the API key picker. Permissions your role doesn't allow are greyed out and can't be ticked. Nothing is ticked for you.
Choose the organisation (general address only), tick what the app may do, and click Allow. You return to the app, connected.

The app then works as you. It sees only the records your role lets you see, and it can only do what you ticked and your role allows today. If your role changes, the connection follows at once. See Auth & scopes.

Claude (claude.ai)

In claude.ai, go to Settings → Connectors → Add custom connector.
Name it (for example "Expedify" or "Expedify – Sales team") and paste the address.
Under authentication, choose Sign in now. For the OAuth client, choose Use Claude's published identity. You don't need a client ID.
Complete the Expedify sign-in and consent screen.

Claude may show "No sign-in: Detected" while you set it up, because our tool list is public. Ignore it and choose Sign in now.

ChatGPT

In ChatGPT, go to Settings → Plugins → Add → Create custom MCP server.
Fill in:
- Name: for example "Expedify" or "Expedify – Sales team"
- Icon (optional): a square PNG under 10 KB. Download the Expedify icon.
- Connection: Server URL, then paste the address
- Authentication: OAuth. You don't need to change the advanced OAuth settings.
Tick I understand and want to continue, then Create as a plugin.
Complete the Expedify sign-in and consent screen.

If the first connection attempt fails, connect once more. ChatGPT sometimes reads our sign-in details only on the second try.

Gemini

Gemini app (gemini.google.com). Custom apps are available only to personal Google accounts in the US, aged 18 or over, with Gemini in English (Google's help page). Elsewhere, the Add a custom app option doesn't appear. Where it's available:

Go to Settings → Connected Apps → Add a custom app.
Paste the address and click Next. Leave Advanced features empty, because Expedify registers Gemini automatically.
Complete the Expedify sign-in and consent screen.

Gemini Enterprise. A Google Cloud admin adds Expedify as a custom MCP server data store. Gemini Enterprise needs a client ID and secret, which an Expedify owner or admin creates:

In Expedify, go to Settings → Connected Apps → Client IDs → Create. Keep the Gemini redirect address it suggests (https://vertexaisearch.cloud.google.com/oauth-redirect).
Copy the client ID, client secret, MCP server URL, authorization URL and token URL. The secret is shown only once.
In the Google Cloud console, go to Gemini Enterprise → Data stores → Create data store → Custom MCP Server, and paste those five values.
Tick Enable PKCE Support. Expedify requires it.
For Scopes, enter offline_access. People choose their actual permissions on the Expedify consent screen.
Gemini Enterprise allows up to 100 enabled actions at a time (Google's guide). Enable the tools your team needs.

A client ID belongs to one organisation, so everyone signing in through it connects that organisation.

Disconnecting

Settings → Connected Apps lists your connections, and owners and admins see everyone's in the organisation. Click Revoke and the app loses access at once. Removing the connector inside the app also ends it on the app's side.

Connect with an API key

This is for developer tools and your own agents. It sends a scoped API key on every request instead of signing in.

The server, in one line

Endpoint: https://api.expedify.ai/v1/mcp
Transport: Streamable HTTP, JSON-RPC (initialize / tools/list / tools/call).
Auth: Authorization: Bearer agx_<key>, a scoped API key. The parser is lenient: it accepts Bearer agx_… or a bare agx_….
Discovery is public: tools/list needs no auth. Execution (tools/call) requires the key, and scope, tenant and ACL checks apply.
No SSE / session: GET /v1/mcp returns 405 (we push no server→client notifications). This is MCP-spec-compliant; clients handle it.

Get a key: Settings → API Keys (owner/admin) → scope picker → creates an agx_ key with the {entity}:{read|write} and capability scopes you choose. Prefer least scope: read-only if the agent only queries. Secret keys are shown once; copy at creation.

The key is the org selector

Every agx_ key belongs to exactly one organization and carries its tenant binding + scopes. There's no "pick an org" step in any client. Connect with a key from the org you want to reach. A teammate in several orgs adds one MCP server per org, each with that org's key and a distinct name.

1. Claude Code (native HTTP — simplest)

Claude Code speaks HTTP MCP directly — no bridge.

claude mcp add --transport http expedify https://api.expedify.ai/v1/mcp \
  --header "Authorization: Bearer agx_<your_key>"

Default scope is local (this project). Use -s user for all projects.
Verify: claude mcp list → expedify: … (HTTP) - ✓ Connected.
Restart the Claude Code session to load it — tools then appear as mcp__expedify__search_contacts, etc.
Remove with claude mcp remove expedify.

Then just ask: "Use Expedify to search my most recent contacts."

2. Claude Desktop (via the `mcp-remote` bridge)

Claude Desktop's config is stdio-only, so an HTTP server needs the mcp-remote stdio↔HTTP bridge (needs Node / npx).

Config file (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "expedify": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.expedify.ai/v1/mcp",
        "--header", "Authorization:agx_<your_key>"
      ]
    }
  }
}

Use the bare token (Authorization:agx_…, no Bearer, no space) — mcp-remote has a header-value space-splitting bug; our lenient parser accepts the bare key.
Merge into existing config (don't clobber other servers). Fully quit (Cmd+Q) and reopen — config is read only at launch.
Tools show under the 🔨 / connectors indicator.

3. MCP Inspector (interactive testing)

npx @modelcontextprotocol/inspector

In the UI: Transport Streamable HTTP · URL https://api.expedify.ai/v1/mcp · Authentication → Bearer Token = agx_<key>. Connect → Tools → List Tools → run search_contacts.

4. n8n (MCP Client Tool node)

Point n8n's MCP Client Tool node at https://api.expedify.ai/v1/mcp with header Authorization: Bearer agx_…. (n8n Cloud needs a public URL — a local server won't be reachable.)

Troubleshooting

Symptom	Cause / fix
`-32001: Missing or malformed Authorization` on `tools/call`	Auth header not attached. Set the Bearer/key in the client's auth field. (`tools/list` works without it — expected.)
`mcp-remote` only sends part of the token	The space bug — use the bare token form `Authorization:agx_…`.
Client logs a `GET … 405`	Expected — no server→SSE stream; spec-compliant, ignore.
Tools don't appear after adding	MCP loads at session/app start — restart Claude Code session / quit-reopen Claude Desktop.
Everything 401 / unreachable	Wrong or rotated key.
A new workflow tool you turned on isn't listed	Reconnect the client — `tools/list` is read at connect time.
"A server with this URL already exists" when adding a second Expedify connector	Chat apps allow one connector per address. Use the other organisation's own address from Settings → Connected Apps.
"You are not a member of …" on the consent screen	The address belongs to an organisation your account isn't in. Log in with the right account, or use your own organisation's address.
"This sign-in is for a different organisation"	The connector's address changed to another organisation. Reconnect, and sign in to that organisation.
A tool is missing in ChatGPT or Claude	The app sees only tools for the permissions you ticked. Reconnect and tick the permission, if your role allows it.
Gemini has no Add a custom app option	Custom apps in the Gemini app are US-only for now. Gemini Enterprise works in other regions.

Treat the key like a password

On production the agx_ key is a real credential. Mint least-scope, per-person keys; never share; rotate on offboarding (Settings → API Keys → Rotate), then update the client config.

Which address to use​

Sign in from a chat app​

What you'll see​

Claude (claude.ai)​

ChatGPT​

Gemini​

Disconnecting​

Connect with an API key​

The server, in one line​

1. Claude Code (native HTTP — simplest)​

2. Claude Desktop (via the mcp-remote bridge)​

3. MCP Inspector (interactive testing)​

4. n8n (MCP Client Tool node)​

Troubleshooting​