Skip to content
shuffl
Get started

Searches the public product guides only. Nothing from a workspace is read, and questions are not saved.

← All guides

Use Shuffl with your agent

Use the built-in assistant, or connect your own agent over MCP, the API, the SDK or the CLI.

Workspace administrators and agent builders

Read as MarkdownAll guides as textAgent documentation index

App links open your signed-in workspace. Check the selected workspace before making changes.

Use the built-in assistant

Open Chat in your workspace, ask about an approved source and follow the citation. The built-in assistant doesn’t need an API key. Workspace membership, employee access and source visibility still apply.

Mello can also act in Shuffl on a person’s behalf, within what their role allows. Reads run at once. Anything that changes something is prepared first and shown as a card in Chat or in Slack, and runs only when the person chooses Run. Credentials, exports, HR request cases, identity links and billing are never offered as actions, and neither is answering a Pulse question or a new hire check-in.

You can also ask about the People directory: someone’s manager or reports, their team or department, who is on a team, and how to reach a colleague. These answers come from the current People directory, not published knowledge, and cite the person or unit in People. If the directory doesn’t hold a field, the assistant says it isn’t recorded rather than guessing. It doesn’t discuss access, pay, benefits, performance or HR matters. In a shared Slack channel or group message it can’t use the directory and asks you to message it directly. Requests to change a manager, team or record, and concerns about a person, go to Contact HR, which sends a reviewed request to your HR responders.

Connect an existing agent

Choose MCP if your agent should work in Shuffl through a remote MCP server, connecting with OAuth in your browser or with an API key sent as a bearer header. Choose the API, TypeScript SDK or CLI to script the same operations. There’s one kind of API key: its MCP permission turns on MCP access, and its endpoint permissions decide what it can do, over HTTP and as MCP tools alike.

Workspace setup opens with Set this up with your agent: copy the prompt into your agent and it works through setup over MCP, asking you before it publishes or invites anyone. Steps for other agents shows the steps for Claude, Claude Code, Codex, Cursor, ChatGPT, VS Code or another client; the client asks for consent in your browser with OAuth and appears under OAuth connections, with no API key. For the API, SDK or CLI, create a key in Manage → Settings → API keys, which only administrators can open, with one-time copy, 30-day expiry and revocation; a key can also carry MCP access for a client that only sends a bearer header. The SDK and CLI install from npm as @shuffl/sdk and @shuffl/cli.

After you create a key, Check connection tests it against the endpoints your agent will use: a tools/list request to the MCP server if the key has MCP access, and the permissions request to the API. It lists the key’s tools and endpoint permissions, and explains a denial, revoked key, rate limit or network failure. It checks the key, not whether a particular agent product is compatible.

Start with a capability read

  1. Sign in, select the workspace and create a separate credential for this integration. Copy the one-time secret into your credential manager.
  2. For MCP, call get_team, then search_knowledge. For the API, SDK or CLI, read teams.current and permissions.list, then use only endpoints you’ve granted, such as knowledge.search.
  3. Check the returned workspace and capabilities before running the integration. Empty knowledge results mean no current matching source is visible to the connected person. They don’t tell you anything about company policy.

The application origin is https://shuffl-rebuild.vercel.app. Send credentials over HTTPS, in the Authorization header, only to the deployment that issued them. Keep them out of prompts, URLs, logs and public documents. A successful read confirms that one request works, not every agent client, model or provider action.

Add actions deliberately

The API, SDK and CLI include reviewed management operations as well as reads. Grant each operation separately; Write doesn’t include Read. Check required inputs, confirmation, revisions and request keys in the reference before making changes. Over MCP, an API key’s endpoint permissions are its tools, with the same checks.

OAuth consent, billing confirmation and provider installation still go through the browser. An endpoint being in the catalog doesn’t mean every provider is configured for your workspace. Revoking a credential stops future calls but can’t erase what an external agent already saved.