Connecting an AI client

Conduit is the gateway between your AI client and the vendor tools your organization has connected. To use those tools, you point your AI client at your organization’s Conduit MCP endpoint and sign in once. This guide walks through it.

You do not install Conduit — it is a hosted gateway. You connect an MCP client to it.

Conduit speaks the standard Model Context Protocol (MCP), so any MCP-capable client works — Claude Desktop and Claude Code are the worked examples below, but Cline, Continue, Cursor, and other MCP clients connect the same way. See Supported clients for the current list.

Before you start

You need:

• A Conduit account. Your organization invites you; accept the invitation and complete sign-in once in the browser.
• Your Conduit MCP endpoint URL — https://conduit.wyre.ai/v1/mcp. The /v1/mcp endpoint is the unified endpoint: it exposes every vendor your organization has connected, behind one URL.

WYRE-hosted Conduit endpoint

For new setups, use https://conduit.wyre.ai/v1/mcp — the recommended endpoint for the WYRE-hosted Conduit service. Existing clients already configured against https://mcp.wyre.ai/v1/mcp continue to work without changes (same gateway, same auth — no migration needed).

Use the unified endpoint

Connect once to the unified /v1/mcp endpoint above — it exposes every vendor your organization has connected. The older per-vendor endpoints (/v1/{vendor}/mcp, which required a separate OAuth flow and config entry for each vendor) are deprecated; the unified endpoint replaces them.

Connect Claude Code

Claude Code connects to a remote MCP server directly. Run:

claude mcp add --transport http conduit https://conduit.wyre.ai/v1/mcp

The --transport http flag tells Claude Code this is a remote HTTP server (without it, Claude Code would treat the URL as a local command and the add would fail). Flags come before the server name.

On first use, Claude Code opens a browser for sign-in — see First connection below.

Scope note: the command above registers Conduit for your current project only (local scope). To use it across every project, add --scope user:

claude mcp add --scope user --transport http conduit https://conduit.wyre.ai/v1/mcp

Verify:

claude mcp list

You should see ✔ Connected next to conduit.

Connect Perplexity Computer

Perplexity Computer connects to a remote MCP server directly, as a custom connector — no bridge needed. In Perplexity Computer:

1. Open Settings → Connectors and choose Add custom connector (Pro, Max, or Enterprise plans).
2. Give it a name (e.g. Conduit) and paste your endpoint as the MCP server URL: https://conduit.wyre.ai/v1/mcp.
3. Set the authentication method to OAuth, then save.
4. Perplexity opens a browser for sign-in — see First connection below.

Once authorized, your organization’s connected vendors appear as tools that Perplexity’s assistant can call.

Note

Choose OAuth, not an API key — Conduit authenticates clients with OAuth 2.1 + PKCE, so there is no API key to paste. The first connection runs the sign-in flow described below.

Connect Claude.ai (web)

Claude.ai (web) connects to a remote MCP server directly, as a custom connector — no bridge needed. Available on Free (limited to 1 custom connector), Pro, Max, Team, and Enterprise plans.

Free, Pro, and Max

1. Open Customize → Connectors.
2. Choose Add custom connector.
3. Give it a name (e.g. Conduit) and paste your endpoint as the MCP server URL: https://conduit.wyre.ai/v1/mcp. Leave advanced/OAuth fields blank — Conduit handles OAuth.
4. Click Add, then sign in — see First connection below.

Team and Enterprise

An organization owner adds the connector once; each member then connects individually.

Owner, first:

1. Open Organization settings → Connectors → Add → Custom.
2. Choose connector type Web, name it Conduit, set the URL to https://conduit.wyre.ai/v1/mcp, and click Add.

Each member, then:

1. Open Customize → Connectors, find the Conduit (Custom) connector, and click Connect.
2. Sign in — see First connection below.

Note

The connector itself is shared org-wide once an owner adds it, but each member’s OAuth sign-in is separate — an unauthenticated member sees a Connect prompt instead of Conduit’s tools.

Enabling Conduit in a conversation

Once authorized, your organization’s connected vendors appear as tools Claude can call — but Conduit does not enable automatically in every conversation. In a chat, click + in the input area, select Connectors, and toggle Conduit on.

Connect Claude Desktop

Claude Desktop supports two connection methods. The native Custom Connectors method (recommended) needs no extra software.

Native Custom Connectors (recommended)

Available on Pro, Max, Team, and Enterprise plans.

1. Open Claude Desktop.
2. Click the + button next to the message input.
3. Select Connectors → Manage connectors.
4. Click Add custom connector.
5. Set URL to https://conduit.wyre.ai/v1/mcp. Leave request headers empty — Conduit uses OAuth.
6. Click Add, then sign in — see First connection below.
7. Back in Claude Desktop, toggle Conduit on for a conversation from the + → Connectors menu.

Free plan or fallback: the mcp-remote bridge

If you’re on the Free plan, or the native method above isn’t available to you, connect via the mcp-remote bridge below — the same bridge used by Cursor, Cline, Continue, and other stdio-only MCP clients.

Connect via the mcp-remote bridge (for stdio-only clients)

Some MCP clients — Claude Desktop’s Free plan among them — connect only to MCP servers that run locally as a program, not to a remote web address. To reach Conduit from one of those clients, you use mcp-remote: a small community tool (a third-party npm package, not a WYRE component) that runs locally and bridges your client to the remote Conduit endpoint.

Add this to your client’s MCP configuration file — for Claude Desktop, that is claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

(Claude Desktop ships for macOS and Windows only.)

{
  "mcpServers": {
    "conduit": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://conduit.wyre.ai/v1/mcp"]
    }
  }
}

Restart the client. mcp-remote runs on demand (via npx), handles the sign-in flow, and stores the token on the client side. The first connection opens a browser for sign-in.

Note

Use the native connector method above wherever your client supports it — Claude Desktop and Claude.ai both do on paid plans. The mcp-remote bridge is for clients that connect only to local programs, or a plan where native connectors aren’t available.

Connect Cursor, Cline, or Continue

These editors are MCP clients and connect to Conduit the same two ways as the clients above — natively by URL where the client supports remote MCP with OAuth, or through the mcp-remote bridge otherwise. In every example below, use https://conduit.wyre.ai/v1/mcp as the endpoint; the first connection then runs the OAuth sign-in.

Interactive clients sign in with OAuth — there is no API key to paste

Conduit authenticates interactive clients with OAuth 2.1 (a browser sign-in), not a static token. If a client’s native remote connection expects you to paste an API key or bearer token and never opens the sign-in browser, use the mcp-remote bridge instead — it performs the OAuth flow for any client. The exception is an unattended agent that cannot run a browser flow at all: it connects as a service account, by device code or a static agent key. Client config formats and remote-OAuth support change between releases; confirm these against your installed version.

Cursor

Cursor connects to a remote MCP server by URL with OAuth — no bridge needed.

1. Create or open ~/.cursor/mcp.json (available in every project) or .cursor/mcp.json (one project). Expected: the MCP config file, or a new empty file.

2. Add Conduit under mcpServers:

   {
     "mcpServers": {
       "conduit": {
         "url": "https://conduit.wyre.ai/v1/mcp"
       }
     }
   }

3. Save the file and reload Cursor. Expected: Cursor lists the conduit server; the first time you use it, a browser opens for the OAuth sign-in.

You can also add it from Settings → MCP → Add new MCP server instead of editing the file by hand.

Cline (VS Code)

Cline adds remote MCP servers from its MCP Servers panel.

1. In VS Code, open the Cline panel and click the MCP Servers icon. Expected: the MCP Servers view.
2. Open the Remote Servers tab. Enter a Server Name (conduit), the Server URL (https://conduit.wyre.ai/v1/mcp), and choose Streamable HTTP as the transport. Click Add Server. Expected: the server appears in the list.
3. The first time you use a Conduit tool, the OAuth sign-in runs. Expected: Conduit’s tools appear once connected — if it expects a token instead, use the mcp-remote bridge per the caution above.

Continue (VS Code / JetBrains)

Continue configures MCP servers in its config.yaml.

1. Open your Continue config at ~/.continue/config.yaml. Expected: the YAML config.

2. Add Conduit under mcpServers:

   mcpServers:
     - name: Conduit
       type: streamable-http
       url: https://conduit.wyre.ai/v1/mcp

3. Save the file; Continue reloads the config. Expected: on first use the OAuth sign-in runs and Conduit’s tools appear — if not, use the mcp-remote bridge per the caution above.

Connect an unattended agent

An agent that runs unattended on a server — an autonomous assistant, a scheduled job, a platform connector — has no browser to open and nowhere to receive a redirect, so it cannot run the interactive sign-in above. It connects as a service account, and there are two ways to get it a credential:

• Device code — preferred. The agent prints a short code and a URL, a person approves it once from any device, and the agent is left with a refresh-token chain that renews itself from then on.
• Agent key — the fallback, for clients that cannot speak the device flow. A static cak_… bearer in the client’s config: no human needed, ever, but it stays a password sitting in a file.

Either way the agent acts as the service account’s own identity (svc:<org-id>:<client-id>), so it reaches exactly what that account’s team memberships and Access-editor overrides allow, and its calls land in the audit log under that account. The choice below is about how the credential is held, not about what the agent can reach — scope the account first. See Managing access.

Device code (preferred)

Conduit implements the OAuth 2.0 Device Authorization Grant (RFC 8628), the flow built for a client that has no browser and no redirect URI. The agent asks Conduit for a code, shows it to you, and polls while you approve it somewhere else. There is no loopback port, no callback URL, and nothing to install on the agent’s host — you can approve from your phone.

The approval authorizes the agent; it does not make the agent you. Device authorization is only for a confidential service account. A public dynamically registered client — the kind Claude, Cursor, ChatGPT, and Claude Code use for browser sign-in — is refused with unauthorized_client. The token Conduit issues is subjected to the agent (svc:<org-id>:<client-id>), not to the person who clicked Approve. You are saying “this agent may run”, not lending it your account. Browser sign-in for those interactive clients is unchanged: authorization code with PKCE, and an explicit Allow on the consent screen before a code is issued.

1. Create the service account. An org admin creates one on /org/service-clients. The response carries client_id (svc_…) and client_secret once; keep the secret in a secret store or environment variable.

2. Point the agent at Conduit with flow: device. Hermes speaks the flow natively — one line of config. In ~/.hermes/config.yaml:

   mcp_servers:
     conduit:
       url: "https://conduit.wyre.ai/v1/mcp"
       auth: oauth
       oauth:
         client_id: "svc_..."
         client_secret: "..."
         flow: device

3. Start the agent. On its first run it prints a code and a URL, then waits:

   To authorize, open https://conduit.wyre.ai/device and enter code: WDJB-MDBT

4. Approve it once, from any device. Open https://conduit.wyre.ai/device on whatever you have to hand, sign in to Conduit, type the code, and choose Approve (or Deny). Case and dashes are ignored, so wdjb mdbt works. The code is good for 10 minutes; if it lapses, the agent prints a new one.

   You must be an owner or admin of the organization that owns the service account — the same permission needed to create one, since approving is what brings it online. Anyone else gets a refusal, even holding a valid code, which is what stops a code being forwarded to someone outside your organization.

5. The agent picks up the answer on its next poll — it polls every 5 seconds — and connects. That is the only approval it needs.

What the agent holds afterwards is an access token good for 1 hour and a refresh token it rotates to get the next one. Conduit’s refresh window slides: every rotation writes a fresh 30 days, with no absolute cap. An agent that refreshes at least monthly therefore runs indefinitely off that one approval, and no long-lived bearer is left at rest — the thing an agent key would have put in a config file does not exist in this flow. An agent that stays off for more than 30 days loses its refresh token and needs one more approval.

The service account’s client_secret is still a secret, and still belongs in a secret store: Conduit requires it both when the agent opens the device flow and when it redeems the code. That is deliberate. Without it, anyone could start a flow against your agent’s identity, get one of your admins to approve the code, and walk away holding a token that acts as your agent.

Agent key (fallback)

Some MCP clients pin their Authorization header once, at process start, and never run a sign-in flow of any kind — a platform connector that stores a bearer verbatim, for instance. Those use an agent key: a static, long-lived bearer that Conduit accepts directly on /v1/mcp.

1. Mint the key. An org admin creates a service account on /org/service-clients, then mints a key against it: POST /api/orgs/<org-id>/service-clients/<client-id>/agent-key. The 201 response carries agent_key — a cak_… string — exactly once. Only its hash is stored, so it cannot be read back; if you lose it, mint again.

2. Put it in the client’s config as Authorization: Bearer cak_…, read from the environment rather than written into the file. Hermes (~/.hermes/config.yaml):

   mcp_servers:
     conduit:
       url: "https://conduit.wyre.ai/v1/mcp"
       headers:
         Authorization: "Bearer ${env:CONDUIT_AGENT_KEY}"

3. Scope the service account before you hand the key over. The key resolves to the service account’s own identity (svc:<org-id>:<client-id>), so the agent reaches exactly what that account’s team memberships and Access-editor overrides allow, and its calls land in the audit log under that account. The key changes how the agent authenticates, not what it can reach. See Managing access.

There is one key per service account. Mint again to rotate: the new key replaces the old one, which stops working immediately, and the identity — with every grant pointing at it — survives. DELETE on the same path revokes with no replacement. A key can never outlive the service account’s own expiry.

An agent key is a long-lived secret in a config file

It does not expire on its own the way an OAuth session does, and anyone holding it calls your tools as that service account. Use it only where neither OAuth nor the device flow is possible — for interactive clients, OAuth 2.1 + PKCE stays the default. Keep it in a secret store or environment variable, scope the account to the minimum it needs, and rotate or revoke it the moment it may have leaked.

Which one to use

	Device code	Agent key
Human involvement	Once, at first start	None, ever
What sits in the agent’s config	The account’s client_id and client_secret	A cak_… bearer that calls tools as-is
What tool calls use	A 1-hour access token, re-minted from a rotating refresh token	The key itself, unchanged
Expiry	Refresh window slides 30 days on every use; no absolute cap	None of its own — until rotated, revoked, or the account expires
Client requirement	A client that speaks RFC 8628 (Hermes: oauth.flow: device)	Any client that can set a header

Use the device flow unless the client cannot run it.

First connection

The first time a client connects, Conduit runs a standard OAuth 2.1 sign-in — your client (or the mcp-remote bridge) does this for you:

1. The client registers itself with Conduit (dynamic client registration).
2. A browser window opens to sign in. Authenticate with your organization’s identity — email/password or Microsoft / Entra ID.
3. The client receives a token and is connected.

The token is cached and refreshed automatically — you sign in once, not on every session. Conduit’s OAuth flow uses PKCE; an interactive client never pastes a key. (Unattended agents, which have no browser to open, use the device flow or an agent key instead.)

Verify the connection

Once connected, your organization’s connected vendors appear as tools in your client. To confirm:

• Ask your assistant to run a simple read-only tool call against one of your connected vendors.
• The call should return real data from the vendor.

If tools do not appear, see Troubleshooting below.

Troubleshooting

Symptom	Likely cause
No tools appear after connecting	Your organization may not have any vendors connected yet, or your role’s tool allowlist restricts them. Check with your Conduit admin.
Browser sign-in never completes	Make sure pop-ups are allowed for the sign-in window, then retry the connection.
Claude Code add fails or the URL is treated as a command	Make sure --transport http is included and comes before the server name.
A tool call returns a permissions error	Your role may not be granted access to that vendor or tool. Your Conduit admin controls vendor and tool access.
Connection worked, then stopped	Your session may have been revoked, or a vendor credential changed. Reconnect; if it persists, contact your Conduit admin.
An unattended agent gets 401 on every call	Its agent key was revoked, or replaced by a rotation, or its service account expired. Mint a key and update the agent’s config.
POST /oauth/token returns invalid_client with “Invalid client_secret.” or “This is an agent key (cak_…), not the client secret.”	The agent is sending something other than the client secret — often an agent key (cak_…), which /oauth/token does not accept. The secret is shown once, when the service account is created; if it was lost, open Service Accounts, click Reset secret next to the client ID, and use the new secret. The old one stops working immediately.
A device-code agent stops working after a long idle spell	Its refresh token lapsed. The window is 30 days from the last refresh, so an agent that was off for longer needs one more approval — restart it and approve the code it prints.
A device-code agent never gets past authorization_pending	Nobody has approved the code yet, or it expired after 10 minutes. Approve it at /device within the window; the agent prints a fresh code once the old one lapses.

Frequently asked questions

Which AI clients can connect to Conduit?

Any MCP-capable client. Conduit speaks the standard Model Context Protocol, so Claude Desktop, Claude Code, Cline, Continue, Cursor, and other MCP clients all work — there’s no per-vendor lock-in. See Supported clients.

Do I need mcp-remote?

Only if your client doesn’t support native remote MCP connections, or you’re on a plan where the native method isn’t available. Claude Code, Claude.ai, and Claude Desktop (Pro, Max, Team, and Enterprise) all connect natively now. Stdio-only clients, and Claude Desktop’s Free plan, use the mcp-remote bridge instead.

How do I sign in — do I paste an API key?

No API keys. The first time your client connects, Conduit runs a standard OAuth 2.1 sign-in in your browser (email/password or Microsoft / Entra ID). The token is cached and refreshed automatically — you sign in once.

I connected but no tools appear. Why?

Either your organization hasn’t connected any vendors yet, or your role’s tool allowlist restricts them. Your Conduit admin controls which vendors and tools your role can reach.

Related

• Getting started — the admin-side setup that stands up the Conduit endpoint you connect to.
• Vendor connections — how your organization connects the vendors whose tools you see.