diff --git a/app/en/get-started/_meta.tsx b/app/en/get-started/_meta.tsx index 93c4fc3af..589f4674e 100644 --- a/app/en/get-started/_meta.tsx +++ b/app/en/get-started/_meta.tsx @@ -2,6 +2,7 @@ import type { MetaRecord } from "nextra"; export const meta: MetaRecord = { "about-arcade": "About Arcade", + "agent-plugin": "Agent Plugin", setup: "Setup", quickstarts: "Quickstarts", "agent-frameworks": "Agent Frameworks", diff --git a/app/en/get-started/agent-plugin/_meta.tsx b/app/en/get-started/agent-plugin/_meta.tsx new file mode 100644 index 000000000..bce8ae202 --- /dev/null +++ b/app/en/get-started/agent-plugin/_meta.tsx @@ -0,0 +1,15 @@ +import type { MetaRecord } from "nextra"; + +export const meta: MetaRecord = { + index: { + title: "Overview", + }, + "tools-only": { + title: "Tools-only MCP server", + }, + "team-rollout": { + title: "From personal use to team rollout", + }, +}; + +export default meta; diff --git a/app/en/get-started/agent-plugin/page.mdx b/app/en/get-started/agent-plugin/page.mdx new file mode 100644 index 000000000..857a5ada8 --- /dev/null +++ b/app/en/get-started/agent-plugin/page.mdx @@ -0,0 +1,217 @@ +--- +title: "Install the Arcade agent plugin" +description: "Install Arcade in Cursor, Claude Code, VS Code, GitHub Copilot CLI, Codex, or Claude Desktop. Your agent gets tools for every app you connect, with browser sign-in and no API keys." +--- + +import { Callout, Tabs } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Install the Arcade agent plugin + +The Arcade agent plugin bundles a connection to Arcade's hosted MCP gateway with two skills, three commands, and the `arcade-operator` subagent. The gateway gives your agent thousands of tools for email, calendar, chat, issues, docs, and dozens of other apps. The rest of the plugin helps your agent choose and use those tools. You authorize each app in the browser the first time it comes up, with no API keys to create and no gateway to configure. + + + + +Install the Arcade agent plugin in your agent and run your first task against a connected app. + + + + + +1. A supported client: Cursor, Claude Code, VS Code, GitHub Copilot CLI, Codex, or Claude Desktop +2. An Arcade account + + + + + + + The plugin is built for personal use. For team use, consider a dedicated [MCP + Gateway](/operate/governance/mcp-gateways) with a curated tool list. Add a + [User Source](/operate/identity/user-sources) when end users should sign in + through your organization's identity provider. See [from personal use to team + rollout](/get-started/agent-plugin/team-rollout). + + +## Install + +Each client installs plugins differently. Use the path for yours. + + + The cross-client `npx plugins add` command does not finish every client + install. Use the client-native steps below so the gateway and every supported + plugin component load together. + + + + + +Add the Arcade marketplace, then install the plugin: + +```bash +claude plugin marketplace add {{ARCADE_PLUGIN_REPO}} +claude plugin install arcade@arcade +``` + +Run `/reload-plugins` if Claude Code is already open. Verify the install with `claude plugin list` or `/plugin`. + + + + +Add the Arcade marketplace, then install the plugin: + +```bash +codex plugin marketplace add {{ARCADE_PLUGIN_REPO}} +codex plugin add arcade@arcade +``` + +Start a new Codex session or ChatGPT desktop chat. Open `/plugins`, confirm **arcade** is installed and enabled, then confirm the **arcade** MCP server is connected. + +To invoke Arcade explicitly, choose `@Arcade` or use `$arcade:try-arcade`. For team-rollout guidance, use `$arcade:scale-arcade`. Codex does not expose these skills as slash commands. + + + + +For an individual Cursor plan, clone the plugin into Cursor's local plugin directory: + +```bash +git clone https://github.com/{{ARCADE_PLUGIN_REPO}} ~/.cursor/plugins/local/arcade-plugin +``` + +Run **Developer: Reload Window**, then open **Customize** and confirm the Arcade skills, `arcade-operator`, rule, and MCP server are present. + +On Teams and Enterprise plans, an admin must import `https://github.com/{{ARCADE_PLUGIN_REPO}}` under **Dashboard → Plugins & MCPs → Team Marketplaces**. Each person can then install Arcade from **Customize**. + + + + +Open the Command Palette, select **Chat: Install Plugin From Source**, and paste: + +```text +https://github.com/{{ARCADE_PLUGIN_REPO}} +``` + +Turn on `chat.plugins.enabled` if needed, then reload VS Code. Run **MCP: List Servers**, select **arcade**, choose **Start Server**, and sign in when prompted. + + + + +Install with Copilot CLI's plugin command: + +```bash +copilot plugin install {{ARCADE_PLUGIN_REPO}} +``` + +Restart the session or run `/restart`. + + + + +Open **Customize → Plugins → Add marketplace → Add from a repository**, paste `{{ARCADE_PLUGIN_REPO}}`, then install **Arcade** (`arcade@arcade`). + +See the [Claude Desktop guide](/get-started/agent-plugin/tools-only/claude-desktop) for the terminal commands and tools-only connector option. + + + + +After installation, reload your agent or start a new session. Using another client that does not load plugins? Connect to the same gateway with the [tools-only Arcade bundle](/get-started/agent-plugin/tools-only). + +## Sign in + +Authentication happens in two layers: + +1. **Into the gateway.** Your client will ask you to authenticate when it first connects. You sign in to Arcade in the browser, and the client can reach the gateway from then on. +2. **Into each app.** When a task needs an app, your agent gives you a browser sign-in link for the required permissions. After approval, Arcade stores the authorization. You may need to reconnect if the connection expires or a later task needs additional permissions. + +You never give your agent an API key or a password for either layer. To check or manage connections, ask your agent to "Check my Arcade connection," "Show my connected apps," or "Connect Google." You can connect an app before you need it. Clients that support Arcade commands also provide the shortcuts listed below. + +Arcade uses the app connections authorized for your signed-in identity. Authorize only the accounts you intend the agent to use. + +### Privacy + +The current plugin build sends no client-side usage telemetry. The build turns telemetry off, and no environment setting turns it on. Requests you make through Arcade still go to its hosted gateway and the apps you authorize. See [Arcade's privacy policy](https://www.arcade.dev/privacy-policy). + +Gateway sign-in and app authorization stay separate on every Arcade gateway, including the one in the plugin. [Server-level and tool-level authorization](/learn/server-level-vs-tool-level-auth) goes deeper on the split. + +## What you get in each agent + +Every install connects to the same Arcade gateway and gets the same tools. What differs is how much of the rest of the plugin each agent can load. + +| Agent | Tools | Skills | Subagent | Commands | Rule | Hooks | +| ----------------------------------- | :---: | :----: | :------: | :------: | :--: | :------: | +| Cursor IDE and Cloud Agents | ✅ | 2 | ✅ | 3¹ | ✅ | —² | +| Cursor CLI | ✅ | 2 | ✅ | 3 | — | ✅³ | +| Claude Code | ✅ | 2 | ✅ | 3 | — | ✅ | +| Claude Cowork | ✅ | 2 | ✅ | 3 | — | partial⁴ | +| GitHub Copilot CLI | ✅ | 2 | ✅ | — | — | ✅⁵ | +| VS Code | ✅ | 2 | ✅ | — | — | —⁶ | +| Codex and ChatGPT local runtime | ✅ | 2 | — | — | — | —⁷ | +| Claude Desktop Chat | ✅ | 2 | — | — | — | — | +| OpenCode | ✅ | — | — | — | — | — | +| Any other Streamable HTTP MCP client | ✅ | — | — | — | — | — | + +- ¹ Cursor IDE lists the commands on the plugin page but does not show them in the `/` menu. +- ² Cursor IDE and Cloud Agents do not run plugin hooks. The always-apply rule carries the routing guidance instead. +- ³ Cursor CLI runs the session hook but does not load the always-apply rule. +- ⁴ Cowork runs the prompt and subagent hooks but does not add the session-start text to the main conversation. +- ⁵ Copilot CLI runs session and subagent hooks, but drops prompt-hook output from configuration files. +- ⁶ VS Code reads the Copilot hook file but cannot run its Agent Plugins hook commands yet. +- ⁷ Codex does not run Agent Plugins lifecycle hooks yet. + +Here is what each of those is for. + +### Commands + +Cursor, Claude Code, and Cowork load all three commands. Claude Code and Cowork namespace them as `/arcade:arcade-status`, `/arcade:arcade-connect`, and `/arcade:arcade-apps`. + +#### `/arcade-status` + +Reports whether the gateway is reachable, whether you have signed in, and which apps you have authorized. + +#### `/arcade-connect ` + +Authorizes an app on demand, so you are not interrupted mid-task. + +#### `/arcade-apps` + +Lists the apps you have connected and lets you disconnect one. + +### Skills + +Skills are instructions your agent reads on its own, so you do not have to invoke them in most clients. `try-arcade` teaches it to turn a request like "reply to that thread" into the right sequence of tool calls across your apps. `scale-arcade` handles the other kind of question, the one about moving a workflow onto a team gateway, and it walks you through the decisions on [this page](/get-started/agent-plugin/team-rollout) against your own project. Codex does not expose these skills as slash commands. Choose `@Arcade` or `$arcade:try-arcade`, and use `$arcade:scale-arcade` for team-rollout guidance. + +### Subagent + +The `arcade-operator` subagent runs an app task in its own context and reports back just the result. Arcade exposes a lot of tools, and searching them fills a conversation with noise that pushes out your actual work. The operator absorbs that. Cursor, Claude Code, Cowork, Copilot CLI, and VS Code load it. Codex and Claude Desktop Chat do not. + +### Rule and hooks + +The rule and hooks tell your agent that Arcade exists and when reaching for it is the right move, which is the difference between a tool that sits unused and one your agent actually picks up. Cursor IDE and Cloud Agents use an always-apply rule. Cursor CLI, Claude Code, Cowork, and Copilot CLI run the hooks their hosts support. + +The columns thin out because the [Agent Plugins](https://agent-plugins.org) 1.0 specification only makes skills and MCP servers portable. Commands, subagents, hooks, and editor rules are specific to each agent, so the plugin ships them where the agents that support them will find them. + +### How Arcade chooses a connection + +Arcade prefers the plugin's gateway. If it cannot complete a task for a reason other than sign-in or permission denial, your agent may use another already-authorized connection within the task you approved. It checks the intended app account before using another Arcade gateway. Sign-in and permission failures require your attention. The agent does not switch connections to get around them. The plugin instructs your agent to confirm the action and destination before changing something in an app. + +`arcade-operator` falls back only to another authorized Arcade gateway. Fallback to any other tool belongs to the parent agent. + +## Try it + +This gateway includes every [optimized toolkit](/resources/integrations) in the catalog. Try asking your agent: + +- "Send a summary of tomorrow's calendar events to me on Slack." +- "Read my Granola notes from last week, check them against Linear, and file anything I promised that is not a ticket yet. Wait for me before creating anything." +- "Find unread mail that needs a reply. Look the sender up in HubSpot if you can, draft a response, and Slack me the draft before sending." +- "Pull my open GitHub pull requests, my Linear issues, and tomorrow's calendar. Write a standup update and send it to me on Slack." +- "Search my Drive and Notion for the product spec my team uses, then drop a one-paragraph summary in Slack." + +Or ask "What can Arcade do?" and pick a workflow from the answer. + +## Next steps + +- [From personal use to team rollout](/get-started/agent-plugin/team-rollout): move a workflow onto your own gateway +- [Connect to MCP clients](/get-started/mcp-clients): configure a client against a gateway you control +- [Integrations catalog](/resources/integrations): every app and toolkit Arcade supports +- [Agentic development](/get-started/setup/connect-arcade-docs): point your agent at these docs with `llms.txt` diff --git a/app/en/get-started/agent-plugin/team-rollout/page.mdx b/app/en/get-started/agent-plugin/team-rollout/page.mdx new file mode 100644 index 000000000..b0006230c --- /dev/null +++ b/app/en/get-started/agent-plugin/team-rollout/page.mdx @@ -0,0 +1,54 @@ +--- +title: "From personal use to team rollout" +description: "What changes when an Arcade workflow you proved with the agent plugin becomes something a team depends on: a dedicated MCP Gateway, a curated tool list, and how end users sign in." +--- + +import { Callout } from "nextra/components"; + +# From personal use to team rollout + +The [agent plugin](/get-started/agent-plugin) serves one person working on their own. Every install points at the same global gateway URL. Arcade uses the app connections authorized for your signed-in identity. Authorize only the accounts you intend the agent to use. + +What the plugin gives you is a broad tool selection and an identity that is yours alone, which is what you want for your own work. + +Once a team depends on that workflow, three questions you never had to answer start to matter: + +1. Where does your team connect? +2. Which tools can they call? +3. Who is each end user? + +Each one has a section below, in that order. + + + If your client loads the plugin's skills, ask Arcade to help move your + workflow onto a team gateway. In Codex, use `$arcade:scale-arcade`. + + +## Where does your team connect? + +An [MCP Gateway](/operate/governance/mcp-gateways) is the endpoint your team's clients connect to, and it is where you decide what those clients can do. Create a gateway in the relevant Arcade project for the workflow and tool boundary you need from the [Arcade dashboard](https://app.arcade.dev). + +Clients connect to it exactly the way they connected to the plugin's gateway. See the [MCP client guides](/get-started/mcp-clients) for Cursor, Claude Code, Claude Desktop, VS Code, and Copilot. + +## Which tools can they call? + +The gateway is the filter that decides which tools reach your agent. Open the **Allowed Tools** picker on your gateway and select across everything in scope: Arcade-hosted toolkits from the [integrations catalog](/resources/integrations), [remote MCP servers](/operate/governance/remote-mcp-servers) you register, and your own [custom MCP servers](/build/create-tools/tool-basics/build-mcp-server) deployed with [Arcade Deploy](/build/arcade-deploy). + +A smaller, deliberate tool list makes agents more accurate, not less capable. Save the gateway and connected clients see the new list on their next request, with no restart. + +Beyond the allowlist, [contextual access](/operate/governance/contextual-access) lets you allow or deny each individual tool call as it arrives, and [audit logs](/operate/governance/audit-logs) and [tool executions](/operate/governance/tool-executions) show you what actually ran. + +## Who is each end user? + +When you are the only user, signing in to each app yourself is enough. In production, each of your end users needs their own authorization, so an agent acting for one person can never reach another person's data. + +Choose how your end users sign in. Internal teams whose users are Arcade project members can use [Arcade Auth](/operate/identity/user-sources#when-to-use-a-user-source). If users already have identities in your organization's OIDC provider, configure a [User Source](/operate/identity/user-sources) on the gateway. + +## Building your own product? + +Connecting a client to a gateway takes the least work, and for many teams it is the whole rollout. When you are building your own product rather than configuring an agent, call Arcade directly instead: + +- [Arcade API reference](/references/api): the REST surface for tool calling and authorization +- [Agent frameworks](/get-started/agent-frameworks) for LangChain, CrewAI, OpenAI Agents, Google ADK, Mastra, Vercel AI SDK, and more +- [Get an API key](/get-started/setup/api-keys): required once you are calling Arcade from your own code +- [Build user-facing agents](/build/user-facing-agents): patterns for handling authorization on behalf of your users diff --git a/app/en/get-started/agent-plugin/tools-only/_meta.tsx b/app/en/get-started/agent-plugin/tools-only/_meta.tsx new file mode 100644 index 000000000..4187c208e --- /dev/null +++ b/app/en/get-started/agent-plugin/tools-only/_meta.tsx @@ -0,0 +1,15 @@ +import type { MetaRecord } from "nextra"; + +export const meta: MetaRecord = { + index: { + title: "Overview", + }, + "claude-desktop": { + title: "Claude Desktop", + }, + "any-mcp-client": { + title: "Any MCP client", + }, +}; + +export default meta; diff --git a/app/en/get-started/agent-plugin/tools-only/any-mcp-client/mcp-client-installer.tsx b/app/en/get-started/agent-plugin/tools-only/any-mcp-client/mcp-client-installer.tsx new file mode 100644 index 000000000..fb78b2352 --- /dev/null +++ b/app/en/get-started/agent-plugin/tools-only/any-mcp-client/mcp-client-installer.tsx @@ -0,0 +1,77 @@ +"use client"; + +import { + Select, + SelectContent, + SelectItem, + SelectTrigger, +} from "@arcadeai/design-system"; +import { + getMcpClientMeta, + MCPInstallButton, + type McpClientId, +} from "@arcadeai/ui-kit/mcp-gateway-connect"; +import { useState } from "react"; +import { + AGENT_PLUGIN_ENGINE_PUBLIC_URL, + AGENT_PLUGIN_GATEWAY_SLUG, +} from "@/lib/agent-plugin"; + +const INSTALL_CLIENTS = [ + "cursor", + "vscode", +] as const satisfies readonly McpClientId[]; + +type InstallClient = (typeof INSTALL_CLIENTS)[number]; + +function isInstallClient(value: string | null): value is InstallClient { + return value === "cursor" || value === "vscode"; +} + +function ClientOption({ clientId }: { clientId: InstallClient }) { + const client = getMcpClientMeta(clientId); + + return ( + + + {client.logo} + + {client.name} + + ); +} + +export function MCPClientInstaller() { + const [selectedClient, setSelectedClient] = useState("cursor"); + + return ( +
+ + + +
+ ); +} diff --git a/app/en/get-started/agent-plugin/tools-only/any-mcp-client/page.mdx b/app/en/get-started/agent-plugin/tools-only/any-mcp-client/page.mdx new file mode 100644 index 000000000..4e3ad3847 --- /dev/null +++ b/app/en/get-started/agent-plugin/tools-only/any-mcp-client/page.mdx @@ -0,0 +1,40 @@ +--- +title: "Install Arcade in any MCP client" +description: "Point any Streamable HTTP MCP client at the Arcade gateway to get tools for every app you connect, with no API key and no plugin install." +--- + +import { MCPClientInstaller } from "./mcp-client-installer"; + +# Install Arcade in any MCP client + +Any client that speaks the Streamable HTTP MCP transport can use Arcade tools, OpenCode included. Add this as an MCP server: + +```text +{{ARCADE_PLUGIN_GATEWAY_URL}} +``` + +Your agent gets every tool on the gateway. Nothing else about how you use it changes. + +## One-click install + +Cursor and VS Code can add the gateway without editing any config: + + + +Both of those clients also load the full plugin, so use these only if you want the tools on their own. [Install the agent plugin](/get-started/agent-plugin) for the rest. + +## Sign in + +Your client signs you in to Arcade when it first connects. When a task needs an app, your agent gives you a browser sign-in link for the required permissions. You may need to reconnect if the connection expires or a later task needs additional permissions. See [signing in](/get-started/agent-plugin/tools-only#sign-in) for how the two layers fit together. + +## Try it + +Ask your agent for an outcome rather than naming a tool. The first time a task needs an app you have not authorized, your agent hands you a link. Approve it and the rest of the task continues, including steps that land in a different app. + +See [sample prompts](/get-started/agent-plugin#try-it) on the main install page, or ask "What apps can Arcade use?" + +## Next steps + +- [Tools-only MCP server](/get-started/agent-plugin/tools-only): what you give up by skipping the plugin +- [Install the agent plugin](/get-started/agent-plugin): use the client-native install for Cursor, Claude Code, VS Code, Copilot CLI, Codex, or Claude Desktop +- [Connect to MCP clients](/get-started/mcp-clients): point a client at a gateway you control, with your own tool list diff --git a/app/en/get-started/agent-plugin/tools-only/claude-desktop/page.mdx b/app/en/get-started/agent-plugin/tools-only/claude-desktop/page.mdx new file mode 100644 index 000000000..654024b8d --- /dev/null +++ b/app/en/get-started/agent-plugin/tools-only/claude-desktop/page.mdx @@ -0,0 +1,79 @@ +--- +title: "Install Arcade in Claude Desktop" +description: "Add the Arcade plugin from a Claude Desktop marketplace for tools and skills, or connect the gateway as a custom connector for tools only." +--- + +import { Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Install Arcade in Claude Desktop + +Add Arcade through Claude Desktop's plugin marketplace. Chat gets tools and both skills. Cowork and Code also load the operator, commands, and supported routing hooks when you enable the plugin there. + + + + +Install Arcade in Claude Desktop and run a task against one of your apps. + + + + + +1. Claude Desktop with plugin marketplace support +2. An Arcade account + + + + + + + Using Claude Code inside the desktop app? You can also install Arcade with + the Claude Code marketplace commands below. + + +## Install the plugin + +**Customize → Plugins → Add marketplace → Add from a repository** → paste: + +```text +{{ARCADE_PLUGIN_REPO}} +``` + +Then install **Arcade** (`arcade@arcade`). + +From Claude Code in the desktop app, or a terminal: + +```bash +claude plugin marketplace add {{ARCADE_PLUGIN_REPO}} +claude plugin install arcade@arcade +``` + +If Claude Code is already open, run `/reload-plugins`. + +No documented `claude://` link adds a marketplace. The steps on this page are the install. + +## Tools only + +If you only want the gateway without skills, skip the marketplace. Open **Settings → Connectors**, click **Add custom connector**, and paste: + +```text +{{ARCADE_PLUGIN_GATEWAY_URL}} +``` + +Save, then start a new conversation. You get the same tools this way. You lose the skills that teach Claude how to chain tool calls across your apps. See [what you give up](/get-started/agent-plugin/tools-only#what-you-give-up). + +## Sign in + +Connecting Arcade signs you in and links Claude Desktop to the gateway. When a task needs an app, your agent gives you a browser sign-in link for the required permissions. After approval, Arcade stores the authorization. You may need to reconnect if the connection expires or a later task needs additional permissions. You can connect an app before you need it. See [signing in](/get-started/agent-plugin/tools-only#sign-in) for how the two layers fit together. + +## Try it + +Ask Claude for an outcome rather than naming a tool. The first time a task needs an app you have not authorized, Claude hands you a link. Approve it and the rest of the task continues, including steps that land in a different app. + +See [sample prompts](/get-started/agent-plugin#try-it) on the main install page, or ask "What apps can Arcade use?" + +## Next steps + +- [Tools-only MCP server](/get-started/agent-plugin/tools-only): what you give up by skipping the plugin +- [Install the agent plugin](/get-started/agent-plugin): the full experience in Cursor, Claude Code, VS Code, Copilot CLI, or Codex +- [Use Arcade in Claude Desktop with your own gateway](/get-started/mcp-clients/claude-desktop): pick exactly which tools Claude can call diff --git a/app/en/get-started/agent-plugin/tools-only/page.mdx b/app/en/get-started/agent-plugin/tools-only/page.mdx new file mode 100644 index 000000000..f07b263a8 --- /dev/null +++ b/app/en/get-started/agent-plugin/tools-only/page.mdx @@ -0,0 +1,43 @@ +--- +title: "Tools-only MCP server" +description: "Connect any MCP client to the Arcade gateway to get tools for every app you connect, without the agent plugin's skills, commands, or subagent." +--- + +import { SignupLink } from "@/app/_components/analytics"; + +# Tools-only MCP server + +The [agent plugin](/get-started/agent-plugin) ships more than tools: two skills, three commands, and the `arcade-operator` subagent, all of which need a client that loads [agent plugins](https://agent-plugins.org). Any client can still connect to the same gateway and get every tool on it without loading the rest of the plugin. + +That is what this section covers. The gateway URL is: + +```text +{{ARCADE_PLUGIN_GATEWAY_URL}} +``` + +## Install it + +- **[Claude Desktop](/get-started/agent-plugin/tools-only/claude-desktop)** installs the full plugin from a marketplace, or connects with tools only through a custom connector. +- **[Any other MCP client](/get-started/agent-plugin/tools-only/any-mcp-client)** takes the gateway URL directly. Cursor and VS Code also have one-click links. + +## What you give up + +Tools alone still do the work. What you lose is the part that helps your agent use them well: + +- **The skills** teach your agent to turn "reply to that thread" into the right sequence of tool calls, and to walk you through a team rollout when you ask about one. +- **The commands** give you `/arcade-status`, `/arcade-connect`, and `/arcade-apps` for checking and managing connections without leaving your agent. +- **The subagent** keeps tool search out of your main conversation, so it does not crowd out your actual work. + +If your client supports [plugins](https://agent-plugins.org), you should [install the full plugin](/get-started/agent-plugin) instead. + +## Sign in + +No API keys. You authorize twice: your client signs you in to Arcade with your Arcade account when it first connects to the gateway. When a task needs an app, your agent gives you a browser sign-in link for the required permissions. After approval, Arcade stores the authorization. You may need to reconnect if the connection expires or a later task needs additional permissions. You can connect an app before you need it. + +Arcade uses the app connections authorized for your signed-in identity. Authorize only the accounts you intend the agent to use. [Server-level and tool-level authorization](/learn/server-level-vs-tool-level-auth) covers the split in depth. + +## Next steps + +- [Install the agent plugin](/get-started/agent-plugin): use the client-native install for Cursor, Claude Code, VS Code, Copilot CLI, Codex, or Claude Desktop +- [Connect to MCP clients](/get-started/mcp-clients): point a client at a gateway you control, with your own tool list +- [From personal use to team rollout](/get-started/agent-plugin/team-rollout): what changes when a team depends on the workflow diff --git a/app/en/get-started/mcp-clients/claude-code/page.mdx b/app/en/get-started/mcp-clients/claude-code/page.mdx index fcfe7080b..73a553cb5 100644 --- a/app/en/get-started/mcp-clients/claude-code/page.mdx +++ b/app/en/get-started/mcp-clients/claude-code/page.mdx @@ -3,6 +3,13 @@ import { SignupLink } from "@/app/_components/analytics"; # Use Arcade in Claude Code + + **Setting Arcade up for yourself?** The [Arcade agent plugin](/get-started/agent-plugin) + installs through Claude's plugin marketplace, needs no API key, and signs you + in to each app in the browser. This guide is for pointing Claude Code at a + gateway you control, with your own tool list and your own end-user identities. + + @@ -44,4 +51,3 @@ claude mcp list Open Claude Code in your project and ask it to use one of the tools from your gateway. - diff --git a/app/en/get-started/mcp-clients/claude-desktop/page.mdx b/app/en/get-started/mcp-clients/claude-desktop/page.mdx index 9deda727c..aad9ca898 100644 --- a/app/en/get-started/mcp-clients/claude-desktop/page.mdx +++ b/app/en/get-started/mcp-clients/claude-desktop/page.mdx @@ -36,6 +36,14 @@ export const STEP_7_LIGHT_HEIGHT = 2450; # Use Arcade in Claude Desktop + + **Setting Arcade up for yourself?** Install [the Arcade + bundle](/get-started/agent-plugin/tools-only/claude-desktop), which needs no API key and + authorizes each app in the browser. This guide is for pointing Claude Desktop + at a gateway you control, with your own tool list and your own end-user + identities. + + diff --git a/app/en/get-started/mcp-clients/cursor/page.mdx b/app/en/get-started/mcp-clients/cursor/page.mdx index 9e852f132..1fc47e4c3 100644 --- a/app/en/get-started/mcp-clients/cursor/page.mdx +++ b/app/en/get-started/mcp-clients/cursor/page.mdx @@ -8,6 +8,13 @@ import { SignupLink } from "@/app/_components/analytics"; # Use Arcade in Cursor + + **Setting Arcade up for yourself?** The [Arcade agent plugin](/get-started/agent-plugin) + installs from GitHub through Cursor's plugin flow, needs no API key, and signs + you in to each app in the browser. This guide is for pointing Cursor at a + gateway you control, with your own tool list and your own end-user identities. + + Cursor is an MCP client. Point it at an Arcade [MCP Gateway](/operate/governance/mcp-gateways) URL over the Streamable HTTP transport and Cursor's agent can call any tool you selected on that gateway — GitHub, Linear, Gmail, Slack, or any other toolkit from the [Arcade integrations catalog](/resources/integrations), plus tools from your own [custom MCP servers](/build/create-tools/tool-basics/build-mcp-server). diff --git a/app/en/get-started/mcp-clients/github-copilot/page.mdx b/app/en/get-started/mcp-clients/github-copilot/page.mdx index 7d73779ee..85ceaecc2 100644 --- a/app/en/get-started/mcp-clients/github-copilot/page.mdx +++ b/app/en/get-started/mcp-clients/github-copilot/page.mdx @@ -20,6 +20,13 @@ export const VISUAL_STUDIO_STEP_6_HEIGHT = 360; # Use Arcade in GitHub Copilot + + **Setting Arcade up for yourself?** The [Arcade agent plugin](/get-started/agent-plugin) + installs with Copilot CLI's plugin command, needs no API key, and signs you in + to each app in the browser. This guide is for pointing Copilot at a gateway + you control, with your own tool list and your own end-user identities. + + diff --git a/app/en/get-started/mcp-clients/page.mdx b/app/en/get-started/mcp-clients/page.mdx index f9e3177b8..c5623b5ef 100644 --- a/app/en/get-started/mcp-clients/page.mdx +++ b/app/en/get-started/mcp-clients/page.mdx @@ -9,6 +9,10 @@ import { MCPClientGrid } from "./mcp-client-grid"; You can connect [Arcade MCP servers](/resources/integrations) to MCP-compatible clients and development environments to unlock powerful flows for your agents. -Every supported MCP client — Cursor, Claude Desktop, Claude Code, VS Code, GitHub Copilot, and Copilot Studio — connects to an Arcade [MCP Gateway](/operate/governance/mcp-gateways) over the Streamable HTTP transport. The gateway decides which tools the client can call: pick from Arcade-hosted toolkits (GitHub, Linear, Gmail, Slack, Google Calendar, Notion, Jira, Confluence, and dozens more in the [integrations catalog](/resources/integrations)), from [remote MCP servers](/operate/governance/remote-mcp-servers) you registered, and from your own [custom MCP servers](/build/create-tools/tool-basics/build-mcp-server) hosted with [Arcade Deploy](/build/arcade-deploy). +Every supported MCP client, including Cursor, Claude Desktop, Claude Code, VS Code, GitHub Copilot, and Copilot Studio, connects to an Arcade [MCP Gateway](/operate/governance/mcp-gateways) over the Streamable HTTP transport. The gateway decides which tools the client can call: pick from Arcade-hosted toolkits (GitHub, Linear, Gmail, Slack, Google Calendar, Notion, Jira, Confluence, and dozens more in the [integrations catalog](/resources/integrations)), from [remote MCP servers](/operate/governance/remote-mcp-servers) you registered, and from your own [custom MCP servers](/build/create-tools/tool-basics/build-mcp-server) hosted with [Arcade Deploy](/build/arcade-deploy). + +## Setting Arcade up for yourself? + +These guides assume you want your own gateway, with a tool list and end-user identities you control. If you are setting Arcade up for your own work, the [Arcade agent plugin](/get-started/agent-plugin) is faster: install it through your client's plugin flow, skip the API key, and sign in to each app in the browser. diff --git a/app/en/get-started/mcp-clients/visual-studio-code/page.mdx b/app/en/get-started/mcp-clients/visual-studio-code/page.mdx index 1957a3d50..dff90afb6 100644 --- a/app/en/get-started/mcp-clients/visual-studio-code/page.mdx +++ b/app/en/get-started/mcp-clients/visual-studio-code/page.mdx @@ -5,6 +5,13 @@ import { SignupLink } from "@/app/_components/analytics"; In this guide, you'll learn how to connect Visual Studio Code to an Arcade MCP Gateway. + + **Setting Arcade up for yourself?** The [Arcade agent plugin](/get-started/agent-plugin) + installs from source through the Command Palette, needs no API key, and signs + you in to each app in the browser. This guide is for pointing VS Code at a + gateway you control, with your own tool list and your own end-user identities. + + **Production end users with their own identities?** If your end users already sign in to Entra ID, Okta, Auth0, Clerk, or another OIDC provider, configure a [User Source](/operate/identity/user-sources) on your gateway. Arcade redirects each end user to your identity provider on sign-in and identifies them by an OIDC subject claim. @@ -62,4 +69,4 @@ Note: if you are using the Arcade Header auth mode for your MCP Gateway, you wil } ``` -You will not see the authentication prompts when you start the MCP Server in Visual Studio Code because the API Key is passed directly. +You will not see the authentication prompts when you start the MCP Server in Visual Studio Code because the config passes the API key directly. diff --git a/lib/agent-plugin.ts b/lib/agent-plugin.ts new file mode 100644 index 000000000..49346c987 --- /dev/null +++ b/lib/agent-plugin.ts @@ -0,0 +1,13 @@ +/** + * Every install surface for the Arcade agent plugin resolves from the values + * here. Swapping these constants updates the prose, the copyable commands, and + * the one-click install links together. + * + * MDX pages reach these through `{{TOKEN}}` placeholders — see + * `lib/remark-substitute.ts` for the token list. + */ +export const AGENT_PLUGIN_ENGINE_PUBLIC_URL = "https://api.arcade.dev"; +export const AGENT_PLUGIN_GATEWAY_SLUG = "arcade"; +export const AGENT_PLUGIN_GATEWAY_URL = `${AGENT_PLUGIN_ENGINE_PUBLIC_URL}/mcp/${AGENT_PLUGIN_GATEWAY_SLUG}`; + +export const AGENT_PLUGIN_REPO = "ArcadeAI/arcade-plugin"; diff --git a/lib/remark-substitute.ts b/lib/remark-substitute.ts new file mode 100644 index 000000000..ab71fb90d --- /dev/null +++ b/lib/remark-substitute.ts @@ -0,0 +1,60 @@ +import type { Root } from "mdast"; +import { visit } from "unist-util-visit"; +import { AGENT_PLUGIN_GATEWAY_URL, AGENT_PLUGIN_REPO } from "./agent-plugin"; + +/** + * Tokens an MDX page can write as `{{NAME}}`. Prose, inline code, fenced code + * blocks, and link targets all resolve them, which is why pages use these + * instead of importing the constants directly — a fenced code block cannot + * interpolate JavaScript. + */ +export const substitutions: Record = { + ARCADE_PLUGIN_GATEWAY_URL: AGENT_PLUGIN_GATEWAY_URL, + ARCADE_PLUGIN_REPO: AGENT_PLUGIN_REPO, +}; + +/** + * Unknown tokens are left alone. Auth provider reference pages already write + * OAuth placeholders such as `{{client_id}}`, and those have to survive to the + * rendered page. + */ +export function applySubstitutions(value: string): string { + let result = value; + for (const [token, replacement] of Object.entries(substitutions)) { + result = result.split(`{{${token}}}`).join(replacement); + } + return result; +} + +/** + * The shape of a VFile that this plugin touches. Declared here so the plugin + * does not depend on `vfile` directly. + */ +type SourceFile = { value?: unknown }; + +export function remarkSubstitute() { + return (tree: Root, file: SourceFile) => { + // Nextra exports the untouched source string alongside the AST, and that + // copy is what feeds the "copy page" button and the markdown the site + // serves to agents. Substitute there too, or those readers get the raw + // token. + if (typeof file.value === "string") { + file.value = applySubstitutions(file.value); + } + + visit(tree, (node) => { + if ( + node.type === "text" || + node.type === "inlineCode" || + node.type === "code" + ) { + node.value = applySubstitutions(node.value); + return; + } + + if (node.type === "link" || node.type === "definition") { + node.url = applySubstitutions(node.url); + } + }); + }; +} diff --git a/next.config.ts b/next.config.ts index c6a53a2a5..e9da6d70c 100644 --- a/next.config.ts +++ b/next.config.ts @@ -2,6 +2,7 @@ import type { NextConfig } from "next"; import nextra from "nextra"; import { withLlmsTxt } from "./lib/next-plugin-llmstxt"; import { remarkGlossary } from "./lib/remark-glossary"; +import { remarkSubstitute } from "./lib/remark-substitute"; import { stripMarkdownFromSwcPageExtensions } from "./lib/swc-page-extensions"; import { redirects } from "./redirects"; @@ -16,6 +17,7 @@ const withNextra = nextra({ remarkGlossary, { glossaryPath: "./app/en/resources/glossary/page.mdx" }, ], + remarkSubstitute, ], }, }); diff --git a/public/llms.txt b/public/llms.txt index 9dbeba352..a6547d560 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -132,6 +132,7 @@ Arcade docs serve two audiences. Start with the path that matches your goal: - [Evaluate Tools](https://docs.arcade.dev/en/build/create-tools/evaluate-tools): This page teaches you how to systematically test and validate your tools using Arcade's evaluation framework to ensure they perform reliably in production. It provides techniques for measuring tool performance and guiding iterative improvements after initial development. - [Examples](https://docs.arcade.dev/en/resources/examples): This documentation page provides a collection of example applications that utilize Arcade's tools and MCP servers, showcasing various real-world scenarios and integration patterns. Users can explore complete source code and setup instructions for each example, enabling them to quickly understand and implement similar projects. - [Frequently Asked Questions](https://docs.arcade.dev/en/resources/faq): This documentation page provides answers to common questions about the Arcade platform, including how to create and contribute tools, the differences between various API keys, and authentication methods. Users can learn how to build custom tools, manage API keys for team collaboration, and understand +- [From personal use to team rollout](https://docs.arcade.dev/en/get-started/agent-plugin/team-rollout): What changes when an Arcade workflow you proved with the agent plugin becomes something a team depends on: a dedicated MCP Gateway, a curated tool list, and how end users sign in. - [Get Formatted Tool Definitions](https://docs.arcade.dev/en/build/tool-calling/custom-apps/get-tool-definitions): This documentation page teaches developers how to retrieve tool definitions in formats compatible with specific AI model providers using the Arcade Client, including methods to get single tools, multiple tools from a server, or all available tools. It also explains how to convert Arcade tool definitions into Zod schemas for TypeScript projects, enabling type safety and integration with popular AI frameworks like LangChain and Vercel AI SDK. - [Getting Your API Key](https://docs.arcade.dev/en/get-started/setup/api-keys): This documentation page guides users on how to obtain and manage their Arcade API key, detailing the steps for generating keys through both the Arcade dashboard and CLI. It emphasizes the importance of securely storing API keys, as they serve as administrator credentials that grant access to - [Governance](https://docs.arcade.dev/en/operate/governance): This documentation page explains how to govern agent tool usage through access control policies, runtime enforcement, and administrative oversight. It provides guidance on managing tool availability, monitoring tool executions, and reviewing audit logs to maintain security and compliance. @@ -142,6 +143,9 @@ Arcade docs serve two audiences. Start with the path that matches your goal: - [Hybrid MCP servers](https://docs.arcade.dev/en/operate/deploy/on-prem): This documentation page explains how to set up a hybrid MCP server that runs on your own infrastructure while connecting to Arcade Cloud, allowing you to access private resources and keep sensitive data within your network. You'll learn how to run an MCP server with HTTP transport, create a secure tunnel to expose it publicly, register it in Arcade, and test it using the Arcade Playground. - [Identity](https://docs.arcade.dev/en/operate/identity): This page explains how to configure user authentication for Arcade gateways and manage identity providers that connect end users to your system. It provides access to resources for setting up user sources, configuring authentication providers, and implementing secure authentication in production environments. - [In Custom Applications](https://docs.arcade.dev/en/build/tool-calling/custom-apps): This documentation teaches developers how to integrate Arcade tools into custom applications by managing user authentication, checking authorization status, and retrieving tool definitions programmatically. It provides guides for building tool-calling interfaces that handle these core requirements. +- [Install Arcade in any MCP client](https://docs.arcade.dev/en/get-started/agent-plugin/tools-only/any-mcp-client): Point any Streamable HTTP MCP client at the Arcade gateway to get tools for every app you connect, with no API key and no plugin install. +- [Install Arcade in Claude Desktop](https://docs.arcade.dev/en/get-started/agent-plugin/tools-only/claude-desktop): Add the Arcade plugin from a Claude Desktop marketplace for tools and skills, or connect the gateway as a custom connector for tools only. +- [Install the Arcade agent plugin](https://docs.arcade.dev/en/get-started/agent-plugin): Install Arcade in Cursor, Claude Code, VS Code, GitHub Copilot CLI, Codex, or Claude Desktop. Your agent gets tools for every app you connect, with browser sign-in and no API keys. - [Mastra](https://docs.arcade.dev/en/get-started/agent-frameworks/mastra): This documentation page guides users in building a TypeScript AI agent using the Mastra framework, enabling interaction with Gmail and Slack through Arcade tools. Users will learn to create an agent capable of reading emails, sending messages, and summarizing emails for Slack, - [MCP Gateways](https://docs.arcade.dev/en/operate/governance/mcp-gateways): MCP Gateways allow you to combine tools from multiple MCP servers into a single endpoint, enabling centralized management and simplified access for agents, applications, and IDEs. You can create gateways through a dashboard or AI assistant, configure authentication methods, and connect any MCP client that supports Streamable HTTP transport to access the federated tools. - [Microsoft Entra ID](https://docs.arcade.dev/en/operate/identity/user-sources/microsoft-entra-id): This documentation page guides users through configuring Microsoft Entra ID as a user source for MCP Gateways, allowing employees with Microsoft work or school accounts to sign in. It provides step-by-step instructions for registering an app in the Microsoft Entra admin center, including creating a client secret and granting the necessary OIDC permissions, which are then used to create the user source in Arcade. @@ -175,6 +179,7 @@ Arcade docs serve two audiences. Start with the path that matches your goal: - [Tool error handling](https://docs.arcade.dev/en/build/tool-calling/error-handling): This page teaches users how to handle errors when calling tools through Arcade's client libraries, covering structured error types, handling examples in Python/JavaScript/Java, and best practices for robust error management. It explains Arcade's error hierarchy system and shows users how to debug failed tool calls using Arcade's recorded execution history. - [Tool executions](https://docs.arcade.dev/en/operate/governance/tool-executions): Arcade records every tool execution in a project, capturing which tool ran, for which user, when, and its outcome, with inputs and outputs restricted to project admins for security. This page helps developers debug failed tool runs by reviewing exact inputs and outputs, and helps platform operators monitor tool usage and ensure compliance across their projects. - [Tools](https://docs.arcade.dev/en/resources/tools): This documentation page provides an overview of Arcade's ecosystem for AI tools, enabling users to explore a catalog of pre-built integrations, create custom tools, and contribute their own tools to the community. It outlines the benefits of using Arcade tools, such as built +- [Tools-only MCP server](https://docs.arcade.dev/en/get-started/agent-plugin/tools-only): Connect any MCP client to the Arcade gateway to get tools for every app you connect, without the agent plugin's skills, commands, or subagent. - [Types of Tools](https://docs.arcade.dev/en/build/create-tools/improve/types-of-tools): Arcade offers two types of tools—Optimized and Unoptimized—that differ in their design approach but work identically through the same interface. Optimized tools are carefully designed to match AI chat interfaces and improve reliability by handling complex workflows automatically, while Unoptimized tools mirror original HTTP endpoints and require more careful evaluation before production use. Both types can be used seamlessly together in Arcade's Dashboard and SDK clients. - [Understanding `Context` and tools](https://docs.arcade.dev/en/build/create-tools/tool-basics/runtime-data-access): The `Context` class provides tools with access to both runtime capabilities and tool-specific data, such as OAuth tokens, secrets, and user information, as well as features like logging, LLM sampling, user elicitation, and progress reporting. This guide explains how to use the `Context` object that is automatically passed to tools by the MCP server to securely access authentication credentials and leverage runtime features during tool execution. - [Use Arcade in Claude Code](https://docs.arcade.dev/en/get-started/mcp-clients/claude-code): This documentation page guides users on how to connect Claude Code to an Arcade MCP Gateway using the Arcade Headers authentication mode. It outlines the prerequisites for setup, including creating an Arcade account, obtaining an API key, and creating an Arcade MCP Gateway, and provides step-by-step instructions for adding the gateway as a remote HTTP MCP server in Claude Code. diff --git a/redirects.ts b/redirects.ts index c602ed79d..efa7e4e24 100644 --- a/redirects.ts +++ b/redirects.ts @@ -1170,4 +1170,14 @@ export const redirects: Redirect[] = [ destination: "/:locale/build", permanent: true, }, + { + source: "/:locale/get-started/agent-plugin/any-mcp-client", + destination: "/:locale/get-started/agent-plugin/tools-only/any-mcp-client", + permanent: true, + }, + { + source: "/:locale/get-started/agent-plugin/claude-desktop", + destination: "/:locale/get-started/agent-plugin/tools-only/claude-desktop", + permanent: true, + }, ]; diff --git a/styles/config/vocabularies/Arcade/accept.txt b/styles/config/vocabularies/Arcade/accept.txt index b8ee8f233..83516eeaa 100644 --- a/styles/config/vocabularies/Arcade/accept.txt +++ b/styles/config/vocabularies/Arcade/accept.txt @@ -13,6 +13,7 @@ Entra ID Stytch Connected App Connected Apps +Claude Desktop LLM SDK API diff --git a/tests/broken-link-check.test.ts b/tests/broken-link-check.test.ts index 593a89eac..d505e97da 100644 --- a/tests/broken-link-check.test.ts +++ b/tests/broken-link-check.test.ts @@ -3,6 +3,7 @@ import { join } from "node:path"; import fg from "fast-glob"; import { scanURLs, validateFiles } from "next-validate-link"; import { expect, test } from "vitest"; +import { applySubstitutions } from "@/lib/remark-substitute"; import { INTEGRATION_CATEGORIES, normalizeToolkitId, @@ -256,7 +257,15 @@ test( return false; }; - const found = await validateFiles(await fg("app/**/*.{md,mdx}"), { + // Pages write `{{TOKEN}}` placeholders for values that live in one place in + // the codebase, so resolve them before validating or the checker sees the + // literal token as a relative path. + const files = (await fg("app/**/*.{md,mdx}")).map((path) => ({ + path, + content: applySubstitutions(readFileSync(path, "utf-8")), + })); + + const found = await validateFiles(files, { scanned, whitelist, }); diff --git a/tests/remark-substitute.test.ts b/tests/remark-substitute.test.ts new file mode 100644 index 000000000..5be6e3dc5 --- /dev/null +++ b/tests/remark-substitute.test.ts @@ -0,0 +1,82 @@ +import type { Code, Link, Paragraph, Root, Text } from "mdast"; +import { describe, expect, it } from "vitest"; +import { AGENT_PLUGIN_GATEWAY_URL } from "@/lib/agent-plugin"; +import { applySubstitutions, remarkSubstitute } from "@/lib/remark-substitute"; + +const substitute = remarkSubstitute(); + +describe("applySubstitutions", () => { + it("replaces a known token", () => { + expect(applySubstitutions("Paste {{ARCADE_PLUGIN_GATEWAY_URL}}")).toBe( + `Paste ${AGENT_PLUGIN_GATEWAY_URL}` + ); + }); + + it("replaces every occurrence of a token", () => { + const result = applySubstitutions( + "{{ARCADE_PLUGIN_REPO}} and {{ARCADE_PLUGIN_REPO}}" + ); + expect(result).toBe("ArcadeAI/arcade-plugin and ArcadeAI/arcade-plugin"); + }); + + it("leaves unknown tokens alone so OAuth placeholders survive", () => { + expect(applySubstitutions('client_id: "{{client_id}}"')).toBe( + 'client_id: "{{client_id}}"' + ); + }); +}); + +describe("remarkSubstitute", () => { + it("substitutes in the raw source Nextra exports for copy-page and agents", () => { + const file = { + value: "Paste {{ARCADE_PLUGIN_GATEWAY_URL}} as an MCP server.", + }; + const tree: Root = { type: "root", children: [] }; + + substitute(tree, file); + + expect(file.value).toBe( + `Paste ${AGENT_PLUGIN_GATEWAY_URL} as an MCP server.` + ); + }); + + it("substitutes inside fenced code blocks", () => { + const code: Code = { + type: "code", + lang: "text", + value: "{{ARCADE_PLUGIN_GATEWAY_URL}}", + }; + const tree: Root = { type: "root", children: [code] }; + + substitute(tree, {}); + + expect(code.value).toBe(AGENT_PLUGIN_GATEWAY_URL); + }); + + it("substitutes inside link targets", () => { + const link: Link = { + type: "link", + url: "{{ARCADE_PLUGIN_GATEWAY_URL}}", + children: [], + }; + const paragraph: Paragraph = { type: "paragraph", children: [link] }; + const tree: Root = { type: "root", children: [paragraph] }; + + substitute(tree, {}); + + expect(link.url).toBe(AGENT_PLUGIN_GATEWAY_URL); + }); + + it("substitutes inside prose", () => { + const text: Text = { + type: "text", + value: "Install {{ARCADE_PLUGIN_REPO}} to start.", + }; + const paragraph: Paragraph = { type: "paragraph", children: [text] }; + const tree: Root = { type: "root", children: [paragraph] }; + + substitute(tree, {}); + + expect(text.value).toBe("Install ArcadeAI/arcade-plugin to start."); + }); +});