Connect an MCP client

Create an API key for MCP

1. Sign in as an administrator, select the workspace and open Workspace settings → API keys → New API key. Keep the MCP permission selected under MCP server.
2. Name the key, acknowledge external access and save the one-time secret in the client’s secret store. Use one key per client.
3. Optionally choose Check connection. It sends one tools/list request with the key and lists the tools it can call. The check counts toward the key’s budget.
4. In the check, 401 means the key isn’t accepted, 403 that it lacks the MCP permission, and a network failure names the unreachable endpoint.
5. Configure the remote Streamable HTTP endpoint https://shuffl.ai/api/mcp. The client must send Authorization: Bearer with the API key on every request.

Anyone in a workspace can connect their own agent.

Connected apps also shows steps for other agents and lists your connections, each with Disconnect. Administrators see everyone’s connections and keys in Workspace settings → API keys.

• Open Connected apps
• Open 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.
   Shell

   https://shuffl.ai/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 →

Connect Claude Code

1. Run:
   Shell

   claude mcp add --scope user \
     --transport http shuffl \
     https://shuffl.ai/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:
   Shell

   claude mcp add --scope user \
     --transport http shuffl \
     https://shuffl.ai/api/mcp \
     --header "Authorization: Bearer $SHUFFL_API_KEY"

• Claude Code MCP guide →

Connect Codex

1. Run this, then allow access in your browser:
   Shell

   codex mcp add shuffl \
     --url https://shuffl.ai/api/mcp

2. If the browser doesn’t open, sign in with:
   Shell

   codex mcp login shuffl

With an API key

1. Set SHUFFL_API_KEY to your key, then run:
   Shell

   codex mcp add shuffl \
     --url https://shuffl.ai/api/mcp \
     --bearer-token-env-var SHUFFL_API_KEY

• Codex MCP guide →

Connect Cursor

1. Choose Add to Cursor, or add this to ~/.cursor/mcp.json:
   Add to Cursor
   JSON

   {
     "mcpServers": {
       "shuffl": {
         "url": "https://shuffl.ai/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:
   JSON

   {
     "mcpServers": {
       "shuffl": {
         "headers": {
           "Authorization": "Bearer ${env:SHUFFL_API_KEY}"
         },
         "url": "https://shuffl.ai/api/mcp"
       }
     }
   }

• Cursor MCP guide →

Connect ChatGPT

1. In ChatGPT on the web, turn on Developer mode in Settings → Security and login. It needs a paid plan, 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.
   Shell

   https://shuffl.ai/api/mcp

3. Allow access in your browser, then turn on Shuffl from Developer mode in a chat’s + menu.

• ChatGPT custom MCP server guide →

Connect VS Code

1. Choose Install in VS Code, or add this to .vscode/mcp.json:
   Install in VS Code
   JSON

   {
     "servers": {
       "shuffl": {
         "type": "http",
         "url": "https://shuffl.ai/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:
   JSON

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

• VS Code MCP guide →

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.
   Shell

   https://shuffl.ai/api/mcp

With an API key

1. A client that only sends a header uses an API key with MCP access on every request:
   Shell

   Authorization: Bearer <your API key>

2. The SDK, CLI and HTTP API use this base URL with the same kind of key:
   Shell

   https://shuffl.ai

3. Check a key over HTTP:
   Shell

   curl https://shuffl.ai/api/v1/permissions \
     -H "Authorization: Bearer $SHUFFL_API_KEY"

4. Install the SDK or CLI:
   Shell

   npm install @shuffl/sdk
   npm install --global @shuffl/cli

• Agent quick start →

Connect with OAuth

1. Give the client the endpoint https://shuffl.ai/api/mcp with no key. It gets a 401, reads the metadata, registers itself and opens the authorization URL.
2. In Claude, use Customize → Connectors → Add custom connector with the recommended sign-in settings.
3. Sign in if asked. Check the client name and return address, choose the workspace, acknowledge external access and choose Allow access. Don’t allow sends the client access_denied.
4. The client exchanges the code for tokens and can call the knowledge tools plus the actions you chose. To change its actions, connect again.

Shuffl is an OAuth 2.1 authorization server for its MCP endpoint. The consent screen names the client and its return address.

• Open Connected apps
• Open API keys

Configure a client

Supply the endpoint and key from your environment, never the command line.

The example uses the official @modelcontextprotocol/client package. Any client needs the URL, Streamable HTTP and a bearer header on every request, or the OAuth flow above.

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

All three are annotated read-only and idempotent, and their schemas reject unknown fields, so no argument can pick another workspace or person. The one MCP permission turns on all three.

A credential that also holds knowledge.context gets knowledge_context, which reads the passages around a cited one.

{ "query": "learning budget" }

{ "passages": [ { "sourceId": "…", "versionId": "…", "passageId": "passage-1", "title": "Handbook: learning budget", "quote": "…", "href": "https://shuffl.ai/app/…/knowledge/…?version=…#passage-1" } ] }

Search the guides

Every connection also gets search_docs and the guides as resources, so your agent can learn Shuffl before it acts. They hold these public guides only. Use search_knowledge for your company’s policies.

search_docs takes query (2 to 500 characters) and an optional limit (1 to 10, default 5). Each result has the guide title, section, a url to the section and its text, cut at 1,200 characters.

resources/list lists every guide by its Markdown URI, plus the Shuffl skill. resources/read returns a guide as Markdown.

Each search and read records an analytics event with no content. A search records its result count, never the query.

{ "query": "set up praise", "limit": 3 }

{ "results": [ { "title": "Praise", "section": "…", "url": "https://shuffl.ai/docs/praise#…", "text": "…" } ] }

• Read the Shuffl skill
• Agent documentation index →

Take actions

An API key’s other permissions, and actions chosen at OAuth consent, are MCP tools too, named with dots as underscores: knowledge.sources.publish is knowledge_sources_publish. Each takes its API operation’s input.

A credential lists only the tools it is granted. To change them, create a new key or reconnect.

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 first.

Uploading a PDF in parts is slow through a model. Importing a website or saving article text is usually better.

• Every MCP tool →
• Endpoint permission reference →
• How management writes work →

Ask your agent to…

1. How are our new hires finding their first 90 days? playbooks_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. playbooks_firstDaysCheckIns reads your open check-in and playbooks_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; digest_dismissNudge dismisses it.
5. Which Pulse questions is Mello suggesting? pulse_proposals lists them. pulse_editProposal rewords one, pulse_decideProposal approves or dismisses it, and 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. If your client asks before actions, your agent shows you a write before running it.

• Endpoint permission reference →

Follow citations in the browser

Each passage links to the cited version of its source in the Shuffl reader. The link works only for a signed-in member who can read it; the API key isn’t used there. Ask your agent to include the links.

Signed in, the reader opens the cited version at the passage. Signed out, Shuffl sends you to sign in, then back to that version without the passage anchor.

If you 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 →

Limits and revocation

Shuffl stores only the key’s issuing membership, request window, last tool name and outcome, and last-used time. It never stores your queries, passages or the key itself.

Each action tool call records an analytics event with its outcome and no content.

• Open API keys
• Use Chat

Troubleshoot a connection

• Open API keys

What stays in the browser

Confidential clients, client secrets and other grant types aren’t offered. Only the consent flow above issues OAuth tokens, and they can’t call the REST API or SDK.

Clients that only send a bearer header use an API key with the MCP permission.

• Use the SDK or HTTP API instead →