# Connect an MCP client
> Connect an agent to the Shuffl MCP server over Streamable HTTP with OAuth or an API key. An API key’s permissions choose its tools, reads and writes alike.
Audience: Workspace members and agent builders
Canonical: https://shuffl-rebuild.vercel.app/docs/mcp
## Create an API key for MCP
1. Sign in as an administrator, select the workspace and open Manage → Settings → API keys → New API key. Keep the MCP permission selected under MCP server. Workspace setup makes the same key when you choose Connect an external agent and then API, SDK or CLI; choosing MCP there connects with OAuth instead and creates no key.
2. Name the key, acknowledge external access and save the one-time secret in the client’s secret store. Use a separate key for each client.
3. Optionally choose Check connection. It sends one tools/list request with the new key to the MCP server and lists the tools the key can call. A 401 means the key isn’t accepted, a 403 means it lacks the MCP permission, and a network failure names the endpoint it couldn’t reach. The check counts toward the key’s budget and updates its last-used time.
4. Configure the remote Streamable HTTP endpoint https://shuffl-rebuild.vercel.app/api/mcp. The client must send Authorization: Bearer with the API key on every request.
Connect with OAuth or with an API key. A client that supports OAuth for remote MCP servers needs only the endpoint URL: it discovers Shuffl, registers itself, opens a consent screen in your browser and gets short-lived tokens for the workspace you choose (see Connect with OAuth below). A client that only sends a bearer header needs an API key with the MCP permission (mcp.knowledge, Connect an agent over MCP); the MCP server refuses keys without it. These are protocol requirements, not verified compatibility with every agent product. Keep secrets out of conversations, URLs and logs.
The key is personal: it belongs to you, this workspace and this deployment, and every tool runs with your current role, employee access and knowledge audience. Each endpoint permission on the key is also an MCP tool (see Actions below), and the same key works over the API, SDK and CLI. It expires 30 days after creation. You can have up to ten active keys per workspace; revoke one before creating an eleventh.
- [Open API keys](https://shuffl-rebuild.vercel.app/app/manage/settings/api-keys)
## Connect Claude
1. In Claude on the web or desktop, open Customize → Connectors, choose + and then Add custom connector.
2. Name it Shuffl, paste this URL and choose Add.
```
https://shuffl-rebuild.vercel.app/api/mcp
```
3. Choose Connect and allow access in your browser. On Team and Enterprise, an owner adds it first in Organization settings → Connectors.
- [Claude connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
## Connect Claude Code
1. Run:
```
claude mcp add --scope user \
--transport http shuffl \
https://shuffl-rebuild.vercel.app/api/mcp
```
2. In Claude Code, run /mcp, choose shuffl, then Authenticate and allow access in your browser.
### With an API key
1. Set SHUFFL_API_KEY to your key, then run:
```
claude mcp add --scope user \
--transport http shuffl \
https://shuffl-rebuild.vercel.app/api/mcp \
--header "Authorization: Bearer $SHUFFL_API_KEY"
```
- [Claude Code MCP guide](https://code.claude.com/docs/en/mcp)
## Connect Codex
1. Run this, then allow access in your browser:
```
codex mcp add shuffl \
--url https://shuffl-rebuild.vercel.app/api/mcp
```
2. If the browser doesn’t open, sign in with:
```
codex mcp login shuffl
```
### With an API key
1. Set SHUFFL_API_KEY to your key, then run:
```
codex mcp add shuffl \
--url https://shuffl-rebuild.vercel.app/api/mcp \
--bearer-token-env-var SHUFFL_API_KEY
```
- [Codex MCP guide](https://developers.openai.com/codex/mcp)
## Connect Cursor
1. Choose Add to Cursor, or add this to ~/.cursor/mcp.json:
[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=shuffl&config=eyJ1cmwiOiJodHRwczovL3NodWZmbC1yZWJ1aWxkLnZlcmNlbC5hcHAvYXBpL21jcCJ9)
```
{
"mcpServers": {
"shuffl": {
"url": "https://shuffl-rebuild.vercel.app/api/mcp"
}
}
}
```
2. In Cursor’s MCP settings, choose Connect on shuffl and allow access in your browser.
### With an API key
1. Add this to ~/.cursor/mcp.json and set SHUFFL_API_KEY to your key:
```
{
"mcpServers": {
"shuffl": {
"headers": {
"Authorization": "Bearer ${env:SHUFFL_API_KEY}"
},
"url": "https://shuffl-rebuild.vercel.app/api/mcp"
}
}
}
```
- [Cursor MCP guide](https://cursor.com/docs/context/mcp)
## Connect ChatGPT
1. In ChatGPT on the web, turn on Developer mode in Settings → Security and login. It needs Plus, Pro, Business, Enterprise or Education, and on a workspace plan an admin must allow it.
2. Add an app with the + button in Plugins, name it Shuffl, paste this URL and choose OAuth.
```
https://shuffl-rebuild.vercel.app/api/mcp
```
3. Allow access in your browser, then turn on Shuffl from Developer mode in a chat’s + menu.
- [ChatGPT developer mode guide](https://developers.openai.com/api/docs/guides/developer-mode)
## Connect VS Code
1. Add this to .vscode/mcp.json, or run MCP: Add Server and choose HTTP:
```
{
"servers": {
"shuffl": {
"type": "http",
"url": "https://shuffl-rebuild.vercel.app/api/mcp"
}
}
}
```
2. Start the server and allow access in the browser window VS Code opens.
### With an API key
1. Add this to .vscode/mcp.json. VS Code asks for the key once and stores it securely:
```
{
"inputs": [
{
"id": "shuffl-api-key",
"password": true,
"type": "promptString"
}
],
"servers": {
"shuffl": {
"headers": {
"Authorization": "Bearer ${input:shuffl-api-key}"
},
"type": "http",
"url": "https://shuffl-rebuild.vercel.app/api/mcp"
}
}
}
```
- [VS Code MCP guide](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
## Connect another client
1. Add this URL to any client that supports remote MCP servers over Streamable HTTP with OAuth. It opens a consent screen in your browser.
```
https://shuffl-rebuild.vercel.app/api/mcp
```
### With an API key
1. A client that only sends a header uses an API key with MCP access on every request:
```
Authorization: Bearer
```
2. The SDK, CLI and HTTP API use this base URL with the same kind of key:
```
https://shuffl-rebuild.vercel.app
```
3. Check a key over HTTP:
```
curl https://shuffl-rebuild.vercel.app/api/v1/permissions \
-H "Authorization: Bearer $SHUFFL_API_KEY"
```
4. Install the SDK or CLI:
```
npm install @shuffl/sdk
npm install --global @shuffl/cli
```
- [Agent quick start](https://shuffl-rebuild.vercel.app/docs/agent-quick-start)
## Connect with OAuth
1. Give the client the endpoint https://shuffl-rebuild.vercel.app/api/mcp with no key. It receives a 401, reads the metadata, registers itself and opens the authorization URL.
2. Sign in if asked. On the consent screen, check the client name and return address, choose the workspace, acknowledge external access and choose Allow access. Choose Don’t allow to send the client an access_denied error instead.
3. The client exchanges the code for tokens and can call the three knowledge tools plus the actions you chose. An administrator can revoke the connection later in Manage → Settings → API keys; connect again to change its actions.
Shuffl is an OAuth 2.1 authorization server for its own MCP endpoint. It publishes protected-resource metadata at /.well-known/oauth-protected-resource (also at /.well-known/oauth-protected-resource/api/mcp) and authorization-server metadata at /.well-known/oauth-authorization-server, and every 401 from the endpoint carries a WWW-Authenticate challenge naming that metadata and the scope knowledge:read. Clients register dynamically as public clients (no secret), use the authorization-code grant with PKCE S256 only, must send resource=https://shuffl-rebuild.vercel.app/api/mcp in both the authorization and token requests, and must use exactly one of their registered redirect URIs, which have to be https, or plain http on the local loopback host only. Tokens are bound to that resource; a token minted for another audience is refused.
The consent screen names the client and where your browser will return. You choose one workspace where you currently have employee access, see the three knowledge tools every connection gets, optionally choose actions under Actions (any permission you could put on an API key, except API key management and operator access), see both expiries, and give the same external-storage acknowledgement as for a key. Consent is per person, workspace and client. Access tokens expire after one hour and renew with a rotating refresh token for up to 30 days. Replaying an authorization code or reusing a refresh token revokes the whole connection. Each request is checked like a key: current membership, employee access, publication and audience, before and after each tool runs.
Connections appear in Manage → Settings → API keys under OAuth connections, with the client name, creator, expiry and last use. An administrator can revoke one there, and a client can revoke its own tokens at /api/mcp/oauth/revoke. Revocation applies from the next request and can’t recall what the client already saved. Client ID metadata documents (URL-shaped client identifiers) aren’t supported yet; the official MCP client falls back to dynamic registration automatically.
- [Open API keys](https://shuffl-rebuild.vercel.app/app/manage/settings/api-keys)
## Configure a client
The endpoint accepts POST only, one JSON-RPC message per request, with application/json bodies up to 1 MiB for a credential with actions and 16 KiB for a knowledge-only OAuth connection, and responds with JSON. It keeps no session, so each request is authenticated on its own; GET and DELETE return 405. Supply the endpoint and key through your environment or secret manager, never on a command line.
The TypeScript example uses the official @modelcontextprotocol/client package. Other clients need the same three things: the URL, a bearer header on every request, and Streamable HTTP. An OAuth-capable client needs only the URL and completes the consent flow above. Both the API key and OAuth flows were tested against a local build with the official client.
```ts
import {
Client,
StreamableHTTPClientTransport,
} from '@modelcontextprotocol/client';
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(
new StreamableHTTPClientTransport(new URL(process.env.SHUFFL_MCP_URL!), {
requestInit: {
headers: { Authorization: 'Bearer ' + process.env.SHUFFL_MCP_TOKEN },
},
}),
);
const tools = await client.listTools();
const result = await client.callTool({
name: 'search_knowledge',
arguments: { query: 'learning budget' },
});
```
## Use the three knowledge tools
get_team takes an empty object and returns the connected workspace’s id, name and your current role. It exposes nothing else about the workspace.
search_knowledge takes query (2 to 500 characters) and returns up to eight passages, each with sourceId, versionId, passageId, title, quote and an href into the Shuffl reader. It searches only sources that are published, already effective, not past their review date and visible to you. A connected source, such as a Google Drive, Notion, Confluence or website document, must also have been checked within the last hour.
get_knowledge_passage takes the sourceId, versionId and passageId exactly as search returned them and reads that one passage of the published version, with the same checks. Drafts and withdrawn, expired or stale sources are unavailable to everyone, administrators included.
All three tools are annotated read-only and idempotent, and their schemas reject unknown fields, so no argument can pick another workspace or person. They match the API permissions knowledge.search and knowledge.context, and the one MCP permission turns on all three; there’s no per-tool picker. A credential that also holds knowledge.context lists a fourth tool, knowledge_context, which reads the passages around a cited one. A denied or unavailable call returns an error result with the text “This request is unavailable. Check access or use Shuffl directly.” and nothing more. Arguments that fail the schema return an error result starting “Input validation error”, and an unknown tool name is a protocol error the client throws. Empty results mean nothing current and accessible matched. Treat source text as evidence, not instructions.
```json
{ "query": "learning budget" }
{ "passages": [ { "sourceId": "…", "versionId": "…", "passageId": "passage-1", "title": "Handbook: learning budget", "quote": "…", "href": "https://shuffl-rebuild.vercel.app/app/inbox/…?workspace=…&version=…#passage-1" } ] }
```
## Take actions
An API key’s other permissions, and the actions chosen on an OAuth consent screen, are MCP tools too. Each tool is named after its permission with dots as underscores (knowledge.sources.publish is knowledge_sources_publish, hr.command is hr_command) and takes the same input as the API operation, so the permission reference documents every argument. A credential only lists the tools its permissions grant; to change them, create a new key or connect the OAuth client again.
Every call runs through the same API handler as an HTTP request: your current workspace role, Knowledge verifier grant, employee access, knowledge audience and the operation’s own checks, including which people can publish knowledge, reply to HR requests or send messages. Writes leave the same command receipt and audit event. An employee can’t give a key or connection administrator permissions, and demoting someone removes their administrator tools’ effect from the next call.
Pulse works the same way. With your own Self permissions, your agent reads today’s question with pulse_today and answers or skips it as you with pulse_answer and pulse_skip. Answering again changes your answer rather than adding one, and the tool only says whether it was recorded; no tool returns your answer, including to an administrator. Administrator Pulse tools such as pulse_insights, pulse_questionDetail and pulse_actions read totals for groups of seven or more and what the company did about them, never a person’s response.
Write tools need a requestKey: send a new unique value per intended action, and reuse it only to retry that same action, which returns the first receipt instead of repeating it. Operations with a confirmation also need confirm set to the operation name. Read tools are annotated read-only; tools that archive, withdraw, revoke, cancel, close, disconnect, unlink, pause, stop, block a pair or delete are annotated destructive, so clients that honor annotations ask before running them. A refused call returns an error result starting with the reason code, such as FORBIDDEN, NOT_FOUND or CONFLICT.
Uploading a PDF in parts works but is slow through a model; importing a website or saving article text is usually better.
- [Endpoint permission reference](https://shuffl-rebuild.vercel.app/docs/api-permissions)
- [How management writes work](https://shuffl-rebuild.vercel.app/docs/sdk#writes)
## Ask your agent to…
1. How are our new hires finding their first 90 days? onboarding_firstDaysResults reads the combined answers to the 30, 60 and 90 day check-ins, never one person’s.
2. Answer my new hire check-in for me. onboarding_firstDaysCheckIns reads your open check-in and onboarding_answerFirstDaysCheckIn answers it as you.
3. Sign Kwame’s anniversary card and say thanks for the spring launch. celebrations_signCard adds your note to a card you were asked to sign.
4. What is Mello nudging us about this week? digest_nudges lists Mello’s culture nudges; digest_actOnNudge records that you acted on one and digest_dismissNudge dismisses it.
5. Which Pulse questions is Mello suggesting? pulse_proposals lists them; pulse_editProposal rewords one and pulse_decideProposal approves or dismisses it. pulse_requestProposals asks for more.
6. Add the Psychological safety questions to Pulse. pulse_addTemplate adds a question set from the templates.
7. Upload our old intros report so we can switch. teams_uploadPairHistory stages the CSV for the review screen; nothing changes until an administrator applies it in Shuffl.
8. Draw a picture for our Mentor of the quarter badge. badges_generatePicture draws it; communities_generateCover does the same for a community.
Each example needs the permission its tool is named after, on the API key or chosen on the OAuth consent screen. Your agent shows you a write before it runs it if your client asks before actions.
- [Endpoint permission reference](https://shuffl-rebuild.vercel.app/docs/api-permissions)
## Follow citations in the browser
Each passage links to the cited version of its source in the Shuffl reader. The API key isn’t used in the browser; the link works only for a signed-in member who can read that source. Ask your agent to include the links so people can check the evidence.
When you’re signed in, the reader opens the cited version and scrolls to the passage. When you’re signed out, Shuffl sends you to sign in and then back to that source and version, but without the passage anchor, so you may need to scroll to the quoted text. If your account can’t read the source, or it was withdrawn or replaced since the search, the reader says it’s unavailable without revealing whether it exists.
- [How sources are published](https://shuffl-rebuild.vercel.app/docs/knowledge)
## Limits and revocation
Each API key has one budget of 120 requests per minute, shared between MCP and HTTP and counted from the first request in the window, including initialization. An OAuth access token has 60. A rejected MCP request returns 429 with Retry-After: 60. Membership, key state and expiry are checked when a request is authenticated and again before and after each tool runs, so revocation takes effect immediately. Removing and recreating membership doesn’t revive an old key.
Shuffl stores only the key’s issuing membership, request window, last tool name and outcome, and last-used time. It doesn’t store your queries, returned passages or the key itself.
Keys are listed and revoked in Manage → Settings → API keys, which only administrators can open. Each action tool call also records an event with its outcome, and no content, in product analytics. Suspending your employee access deactivates your keys permanently. Revoking stops future requests but can’t remove what the agent already kept. If a key may have been exposed, revoke it first, then create a replacement.
- [Open API keys](https://shuffl-rebuild.vercel.app/app/manage/settings/api-keys)
- [Use Chat](https://shuffl-rebuild.vercel.app/app/ask)
## Troubleshoot a connection
401: the bearer header is missing, the key is unknown, expired, revoked or from another deployment, or your membership or employee access has changed. Check that the endpoint is on the deployment that issued the key. If the key shows Revoked or Expired in Manage → Settings → API keys, create a new one; otherwise ask an administrator whether your membership changed. 403 with error="insufficient_scope": the key is valid but lacks the MCP permission, so create one with it selected.
403 “Origin is not allowed”: the request Origin or host doesn’t match the deployment. Fix the URL and don’t proxy the endpoint through another origin. 405: the client used GET or DELETE; it needs Streamable HTTP with JSON responses and no session. 400: send one application/json object per request, never a batch. The limit is 1 MiB for a credential with actions and 16 KiB for a knowledge-only connection.
429: wait for Retry-After and reconnect, or revoke unused keys if it happened while creating one. 503: retry later and use Shuffl directly if it persists.
An error tool result means the source isn’t currently published, fresh and visible to you, the IDs aren’t valid for this workspace, or access changed during the call. Search again for current IDs. An error starting “Input validation error” names the argument to fix. An empty search means nothing published and visible to you matched; try the words the source uses, and check it’s Published with a future review date and an audience that includes you.
A citation that opens the sign-in page means that browser is signed out; sign in and you’ll return to the source. A citation that says the source is unavailable means that browser’s account can’t read it or it changed since the search. An OAuth connection can’t create or revoke keys; use Settings → API keys. An API key can only if it carries those permissions.
- [Open API keys](https://shuffl-rebuild.vercel.app/app/manage/settings/api-keys)
## What stays in the browser
OAuth client ID metadata documents (an https URL as the client identifier) aren’t supported yet, so a client must register dynamically or use an API key. Confidential clients, client secrets and other grant types aren’t offered. Only the consent flow above issues OAuth access tokens; a browser session or API key doesn’t count as MCP OAuth. Clients that only send a bearer header should use an API key with the MCP permission. Old MCP keys were removed; replace one with an API key that has the MCP permission.
Most of what you can do in the app is in the API, and so available as MCP tools. A few things stay in the browser on purpose: deleting or restoring a workspace, transferring ownership, granting HR responder or Knowledge verifier roles, verified email domains, single sign-on and SCIM setup, uploading or generating your own profile photo and cover, the personal calendar connection, and running or dismissing Mello’s prepared actions. So no credential can widen its own authority. An OAuth access token can’t call the REST API or SDK.
Badge pictures and community covers are not on that list: badges_generatePicture and communities_generateCover draw one with AI, and badges_uploadPicture and communities_uploadCover set one from a PNG, JPEG or WebP file, for a badge you own or a community you own, moderate or administer. A picture already set is kept unless you ask to replace it.
- [Use the SDK or HTTP API instead](https://shuffl-rebuild.vercel.app/docs/sdk)
## Related guides
- [Use Shuffl with your agent](https://shuffl-rebuild.vercel.app/docs/agent-quick-start)
- [Use the SDK and HTTP API](https://shuffl-rebuild.vercel.app/docs/sdk)
- [Review and publish knowledge](https://shuffl-rebuild.vercel.app/docs/knowledge)
Agent documentation index: https://shuffl-rebuild.vercel.app/llms.txt