diff --git a/app/en/guides/create-tools/improve/types-of-tools/page.mdx b/app/en/guides/create-tools/improve/types-of-tools/page.mdx index ee4bcfab0..aab5caf11 100644 --- a/app/en/guides/create-tools/improve/types-of-tools/page.mdx +++ b/app/en/guides/create-tools/improve/types-of-tools/page.mdx @@ -5,18 +5,20 @@ description: "Learn about Optimized and Unoptimized tools" # Types of Tools +This page explains the two types of tools Arcade offers and how they differ in their design approach. + Arcade offers two types of tools: - Unoptimized tools - Optimized tools -The distinction is merely a matter of how Arcade designs them. Both types of tools can be used seamlessly in the same way. No difference exists in their interfaces, the way they are called, or how you interact with them through the Arcade [Dashboard](https://api.arcade.dev/dashboard/) or the Arcade [SDK clients](/references). +The distinction is how Arcade designs them. Both types of tools work seamlessly in the same way. No difference exists in their interfaces, how you call them, or how you interact with them through the Arcade [Dashboard](https://api.arcade.dev/dashboard/) or the Arcade [SDK clients](/references). -Before we understand the two types, let's first understand the background for why we need to differentiate between them. +Before understanding the two types, first understand the background for why differentiation between them matters. ## Why LLMs perform poorly when calling HTTP APIs -Traditionally, the HTTP APIs offered by upstream services such as GitHub, Google, Slack, etc., were designed to be consumed by human software engineers. When we expose such interfaces for LLMs to call as tools, they usually do not perform very well. +Traditionally, the HTTP APIs offered by upstream services such as GitHub, Google, Slack, etc., developers designed to allow human software engineers to consume them. When these interfaces become available for LLMs to call as tools, they typically do not perform well. One of the main reasons is that the data model of the HTTP API rarely matches the data model of an AI-powered chat interface. @@ -38,26 +40,26 @@ In order to bridge the gap in the data models, the LLM has to make multiple API 3. Open a DM (direct message) channel between the user and John, and get this channel's ID 4. Send the message to the channel -Even the most powerful LLMs usually perform poorly when they need to reason such complex workflows on the fly, not to mention the increased cost and risk of hallucinations. As a result, AI Agents and chatbots that rely on HTTP APIs often end up being unreliable. +Even the most powerful LLMs typically perform poorly when they need to reason such complex workflows on the fly, not to mention the increased cost and risk of hallucinations. As a result, AI Agents and chatbots that rely on HTTP APIs often end up being unreliable. ## Optimized tools -Arcade's Optimized MCP Servers are designed to match the typical data models expected in AI-powered chat interfaces and are subject to evaluation suites to ensure LLMs can safely use them. +Arcade's Optimized MCP servers match the typical data models expected in AI-powered chat interfaces, and evaluation suites test them to ensure LLMs can safely use them. -Following the example above, our Slack MCP Server offers the [`Slack.SendMessage`](/resources/integrations/social-communication/slack#slacksendmessage) tool, which accepts a `username` as argument, matching exactly both the action and argument value expected to be present in the LLM context window. +Following the example above, the Slack MCP server offers the [`Slack.SendMessage`](/resources/integrations/social-communication/slack#slacksendmessage) tool, which accepts a `username` as argument, matching exactly both the action and argument value expected to be present in the LLM context window. When a user says "Send a DM to John asking about a project update", the LLM can directly call the `Slack.SendMessage` tool with the `username` argument, and the tool will take care of the rest. Optimized tools dramatically improve the speed, reliability and cost-effectiveness of AI Agents and chatbots. -Since they require careful design and evaluation, Optimized tools take time and effort to build. Arcade understands that your Agent or chatbot project might need capabilities not yet covered by Arcade's Optimized MCP Servers. For this reason, Arcade also offers low-level Unoptimized MCP Servers (formerly known as Starter MCP Servers). +Since they require careful design and evaluation, Optimized tools take time and effort to build. Arcade understands that your Agent or chatbot project might need capabilities not yet covered by Arcade's Optimized MCP servers. For this reason, Arcade also offers low-level Unoptimized MCP servers (formerly known as Starter MCP servers). ## Unoptimized tools -To provide your Agent or chatbot with more freedom to interact with upstream services, we offer Unoptimized MCP Servers. +To provide your Agent or chatbot with more freedom to interact with upstream services, Arcade offers Unoptimized MCP servers. -Unoptimized tools are heavily influenced by the original API design. Each tool mirrors one HTTP endpoint. +Unoptimized tools heavily reflect the original API design. Each tool mirrors one HTTP endpoint. -Although we redesign the tool name and argument descriptions to make them more suitable for LLMs, Unoptimized tools are still not optimized for LLM usage. Also, they are not subject to evaluation suites like Optimized tools. For those reasons, we recommend thoroughly evaluating each Unoptimized tool with your Agents or chatbots before using it in production. +Although developers redesign the tool name and argument descriptions to make them more suitable for LLMs, Unoptimized tools are still not optimized for LLM usage. Also, they are not subject to evaluation suites like Optimized tools. For those reasons, you should thoroughly evaluate each Unoptimized tool with your Agents or chatbots before using it in production. -When an Optimized tool covers your Agent's needs, we recommend using it instead of an Unoptimized one. Use Unoptimized tools as a complement. Carefully engineer your prompts to ensure your Agent can call them safely. +When an Optimized tool covers your Agent's needs, use it instead of an Unoptimized one. Use Unoptimized tools as a complement. Carefully engineer your prompts to ensure your Agent can call them safely. \ No newline at end of file diff --git a/app/en/references/changelog/page.mdx b/app/en/references/changelog/page.mdx index d2925fe5b..3f8ff480c 100644 --- a/app/en/references/changelog/page.mdx +++ b/app/en/references/changelog/page.mdx @@ -7,12 +7,12 @@ import { Callout } from "nextra/components"; # Changelog -_Here's what's new at Arcade.dev!_ +Here's what's new at Arcade.dev. ## 2026-01-23 **Arcade MCP Servers** -- `[feature - 🚀]` Launched `https://ctl.arcade.dev/mcp` - Arcade's Gateway Assistant. Connect your LLM to help build MCP Gateways and MCP Servers for any agent use case. Learn more about it [here](/guides/mcp-gateways/create-via-ai)! +- `[feature - 🚀]` Launched `https://ctl.arcade.dev/mcp` - Arcade's Gateway Assistant. Connect your LLM to help build MCP Gateways and MCP servers for any agent use case. Learn more about it [here](/guides/mcp-gateways/create-via-ai)! **Platform and Engine** - `[maintenance - 🔧]` Fixed a race condition in `arcade deploy` @@ -39,7 +39,7 @@ _Here's what's new at Arcade.dev!_ ## 2026-01-09 - We've dramatically revamped our documentation to focus on making it easier to get started with Arcade. Update your links and let us know what you think [here](/resources/contact-us)! + This documentation has been dramatically revamped to focus on making it easier to get started with Arcade. Update your links and let the team know what you think [here](/resources/contact-us)! @@ -47,7 +47,7 @@ _Here's what's new at Arcade.dev!_ **Arcade MCP Servers** -- `[feature - 🚀]` Add support for Arcade Evals on MCP Servers +- `[feature - 🚀]` Add support for Arcade Evals on MCP servers - `[maintenance - 🔧]` Replace fcntl with cross-platform portalocker to fix Windows/Powershell errors **Platform and Engine** @@ -67,7 +67,7 @@ _Here's what's new at Arcade.dev!_ ## 2025-12-12 **Arcade MCP Servers** -- `[feature - 🚀]` OAuth authentication for `arcade-mcp` servers. Learn more about it [here](/guides/security/secure-your-mcp-server! +- `[feature - 🚀]` OAuth authentication for `arcade-mcp` servers. Learn more about it [here](/guides/security/secure-your-mcp-server) - `[maintenance - 🔧]` Ability to run multiple uvicorn workers - `[maintenance - 🔧]` Include type annotations for `arcade_mcp_server` @@ -91,11 +91,11 @@ _Here's what's new at Arcade.dev!_ -As of December 1, 2025, we have migrated the MCP servers deployed via `arcade deploy` to our own managed infrastructure. Please ensure you have the latest version of the arcade CLI installed and that you are using the latest version of the `arcade-mcp-server` package. +As of December 1, 2025, the team has migrated the MCP servers deployed via `arcade deploy` to managed infrastructure. Please ensure you have the latest version of the arcade CLI installed and that you are using the latest version of the `arcade-mcp-server` package. **Arcade MCP Servers** -- `[feature - 🚀]` Add tools for project management, pull request, and projects to the Github MCP Server +- `[feature - 🚀]` Add tools for project management, pull request, and projects to the Github MCP server - `[feature - 🚀]` Add Optimized Linear toolkit - `[feature - 🚀]` Add Optimized Ashby toolkit - `[feature - 🚀]` Shorten Jira tool names exceeding Cursor limit @@ -117,23 +117,23 @@ As of December 1, 2025, we have migrated the MCP servers deployed via `arcade de ## 2025-11-21 -**MCP Servers** -- `[feature - 🚀]` Updated Github MCP Sever to support projects, issues, and pull requests +**MCP servers** +- `[feature - 🚀]` Updated Github MCP server to support projects, issues, and pull requests **Platform and Engine** - `[feature - 🚀]` Invite users to projects by email ## 2025-11-14 -**MCP Servers** -- `[feature - 🚀]` Customer.io Starter MCP Servers added -- `[feature - 🚀]` Intercom Starter MCP Server added +**MCP servers** +- `[feature - 🚀]` Customer.io Starter MCP servers added +- `[feature - 🚀]` Intercom Starter MCP server added **Arcade MCP** - `[maintenance - 🔧]` Do not require entrypoint for `arcade configure` for HTTP server **Platform and Engine** -- `[maintenance - 🔧]` Update `arcade deploy` command to support MCP Servers built with `arcade-mcp` +- `[maintenance - 🔧]` Update `arcade deploy` command to support MCP servers built with `arcade-mcp` - `[maintenance - 🔧]` Improve performance of tool execution with large collections of tools ## 2025-11-07 @@ -142,15 +142,15 @@ As of December 1, 2025, we have migrated the MCP servers deployed via `arcade de - `[feature - 🚀]` AddedMailchimp market toolkit - `[feature - 🚀]` Enhanced Hubspot Marketing & CRM toolkit -**MCP Servers** +**MCP servers** - `[maintenance - 🔧]` Better Handling of MCP-specific `Context` usage for managed servers - `[maintenance - 🔧]` Set server version for `@app.tool` and `MCPApp.add_tool` - `[maintenance - 🔧]` Better errors in UI and CLI if `arcade deploy` fails t **Platform and Engine** -- `[feature - 🚀]` Optional customization of OAuth request header format for upstrem MCP Servers +- `[feature - 🚀]` Optional customization of OAuth request header format for upstrem MCP servers - `[bugfix - 🐛]` Fix MCP token refresh -- `[maintenance - 🔧]` Add log viewing for managed MCP Servers +- `[maintenance - 🔧]` Add log viewing for managed MCP servers **Misc** - `[documentation - 📝]` Fix site search @@ -161,7 +161,7 @@ t **Toolkits** - `[feature - 🚀]` Added new HubSpot Marketing & CRM starter tools -- `[feature - 🚀]` Added Exa.ai Starter MCP Server +- `[feature - 🚀]` Added Exa.ai Starter MCP server - `[feature - 🚀]` Added Asana starter toolkit - `[feature - 🚀]` Added Github starter toolkit - `[feature - 🚀]` Added Pylon Starter Toolkit @@ -192,53 +192,53 @@ t **Platform and Engine** -- `[feature - 🚀]` Dashboard: Add redirect_uri to MCP Servers -- `[feature - 🚀]` Dashboard: Add OAuth fields to MCP Servers +- `[feature - 🚀]` Dashboard: Add redirect_uri to MCP servers +- `[feature - 🚀]` Dashboard: Add OAuth fields to MCP servers ## 2025-10-17 - We've updated our documentation to be more clear, consistent, and easier to navigate. This includes updated quickstarts, guides, and reference information. [Let us know what you think](/resources/contact-us)! + The documentation has been updated to be more clear, consistent, and easier to navigate. This includes updated quickstarts, guides, and reference information. [Let the team know what you think](/resources/contact-us)! - This week we released `arcade-mcp`, the best way to build MCP Servers. `arcade-mcp` supersedes the Arcade TDK. Learn more about it [here](/get-started/quickstarts/mcp-server-quickstart)! Detailed reference information for `arcade-mcp` is available [here](/references/mcp/python). + This week `arcade-mcp` was released, the best way to build MCP servers. `arcade-mcp` supersedes the Arcade TDK. Learn more about it [here](/get-started/quickstarts/mcp-server-quickstart)! Detailed reference information for `arcade-mcp` is available [here](/references/mcp/python). - This week MCP Gateways are now generally available! MCP Gateways allow you to federate the tools from multiple MCP Servers into a single collection for easier management, control, and access. Learn more about them [here](/guides/create-tools/mcp-gateways! + This week MCP Gateways are now generally available. MCP Gateways allow you to federate the tools from multiple MCP servers into a single collection for easier management, control, and access. Learn more about them [here](/guides/create-tools/mcp-gateways) - This week projects are now generally available! Projects are a new way to organize your MCP Servers, tools, and secrets for easier management, control, and access. + This week projects are now generally available. Projects are a new way to organize your MCP servers, tools, and secrets for easier management, control, and access. **Toolkits** -- `[feature - 🚀]` `arcade-mcp` is now generally available! Learn more about it [here](/get-started/quickstarts/mcp-server-quickstart)! +- `[feature - 🚀]` `arcade-mcp` is now generally available. Learn more about it [here](/get-started/quickstarts/mcp-server-quickstart) - `[feature - 🚀]` [Toolkits/BrightData] Added BrightData Toolkit -- `[feature - 🚀]` [Toolkits/Figma] Added Figma Starter MCP Server -- `[feature - 🚀]` [Toolkits/Freshservice] Added Freshservice Starter MCP Server -- `[feature - 🚀]` [Toolkits/Cursor Agents] Added Cursor Agents Starter MCP Server -- `[feature - 🚀]` [Toolkits/AirTable] Added AirTable starter MCP Server -- `[feature - 🚀]` [Toolkits/Miro] Added Miro Starter MCP Server -- `[feature - 🚀]` [Toolkits/PagerDuty] Added PagerDuty Starter MCP Server -- `[feature - 🚀]` `arcade deploy` for MCP Servers built with `arcade-mcp` +- `[feature - 🚀]` [Toolkits/Figma] Added Figma Starter MCP server +- `[feature - 🚀]` [Toolkits/Freshservice] Added Freshservice Starter MCP server +- `[feature - 🚀]` [Toolkits/Cursor Agents] Added Cursor Agents Starter MCP server +- `[feature - 🚀]` [Toolkits/AirTable] Added AirTable starter MCP server +- `[feature - 🚀]` [Toolkits/Miro] Added Miro Starter MCP server +- `[feature - 🚀]` [Toolkits/PagerDuty] Added PagerDuty Starter MCP server +- `[feature - 🚀]` `arcade deploy` for MCP servers built with `arcade-mcp` **Platform and Engine** -- `[feature - 🚀]` Dashboard: Allow OAuth on MCP Servers -- `[feature - 🚀]` MCP Gateways are now generally available! Learn more about them [here](/guides/create-tools/mcp-gateways! +- `[feature - 🚀]` Dashboard: Allow OAuth on MCP servers +- `[feature - 🚀]` MCP Gateways are now generally available. Learn more about them [here](/guides/create-tools/mcp-gateways) - `[feature - 🚀]` Projects are now generally available. - `[maintenance - 🔧]` Support remote MCP servers which require DCR (dynamic client registration). **Misc** - `[documentation - 📝]` Updated documentation to be more clear, consistent, and easier to navigate. This includes updated quickstarts, guides, and reference information. -- `[documentation - 📝]` `llms.txt` is now kept up to date and simplified. We've also added a new section to the docs for [agentic development](/get-started/setup/connect-arcade-docs). +- `[documentation - 📝]` `llms.txt` is now kept up to date and simplified. A new section has been added to the docs for [agentic development](/get-started/setup/connect-arcade-docs). ## 2025-10-10 @@ -249,7 +249,7 @@ t - `[feature - 🚀]` [Toolkits/SquareUp] Added SquareUp toolkit - `[feature - 🚀]` [Toolkits/Xero] Xero API Starter MCP server -**MCP Servers** +**MCP servers** - `[feature - 🚀]` Added reference area to `arcade-mcp` docs ([PR #488](https://github.com/ArcadeAI/docs/pull/488)) @@ -265,8 +265,8 @@ t **Toolkits** -- `[feature - 🚀]` Box.com Starter MCP Server released ([docs](/resources/integrations/productivity/box-api)) -- `[feature - 🚀]` Stripe Starter MCP Server released ([docs](/resources/integrations/payments/stripe_api)) +- `[feature - 🚀]` Box.com Starter MCP server released ([docs](/resources/integrations/productivity/box-api)) +- `[feature - 🚀]` Stripe Starter MCP server released ([docs](/resources/integrations/payments/stripe_api)) **Misc** @@ -277,10 +277,10 @@ t **Toolkits** - `[feature - 🚀]` Introduce [Unoptimized tools](/guides/create-tools/improve/types-of-tools), a new type of tool that mirrors the original HTTP API design of the upstream service. -- `[feature - 🚀]` Release Slack started MCP Server which contains support for most of the Slack API. -- `[feature - 🚀]` Include advanced error handling in the following MCP Servers: Google, Microsoft, Slack, and Asana. Learn more about handling tool errors [here](/guides/create-tools/error-handling/useful-tool-errors). -- `[bugfix - 🐛]` [MCP Servers/MS Teams] Fix get_chat_metadata by chat's users -- `[feature - 🚀]` [MCP Servers/confluence] Adding WhoAmI tools for Confluence +- `[feature - 🚀]` Release Slack started MCP server which contains support for most of the Slack API. +- `[feature - 🚀]` Include advanced error handling in the following MCP servers: Google, Microsoft, Slack, and Asana. Learn more about handling tool errors [here](/guides/create-tools/error-handling/useful-tool-errors). +- `[bugfix - 🐛]` [MCP servers/MS Teams] Fix get_chat_metadata by chat's users +- `[feature - 🚀]` [MCP servers/confluence] Adding WhoAmI tools for Confluence **CLI and TDK** @@ -288,19 +288,19 @@ t **Misc** -- `[documentation - 📝]` Documents API wrapper vs LLM-native MCP Servers; includes Slack API wrapper MCP Server docs +- `[documentation - 📝]` Documents API wrapper vs LLM-native MCP servers; includes Slack API wrapper MCP server docs ## 2025-09-19 **Toolkits** - `[feature - 🚀]` [Toolkits/ClickUp] Removing no content additional messages in Evals -- `[feature - 🚀]` [Toolkits/MongoDB] Add analytics MongoDB MCP Server ([PR #548](https://github.com/ArcadeAI/arcade-ai/pull/548)) -- `[feature - 🚀]` [MCP Servers/HubSpot] Adding HubSpot MCP Server enhancements ([PR #441](https://github.com/ArcadeAI/docs/pull/441)) +- `[feature - 🚀]` [Toolkits/MongoDB] Add analytics MongoDB MCP server ([PR #548](https://github.com/ArcadeAI/arcade-ai/pull/548)) +- `[feature - 🚀]` [MCP servers/HubSpot] Adding HubSpot MCP server enhancements ([PR #441](https://github.com/ArcadeAI/docs/pull/441)) **CLI and TDK** -- `[maintenance - 🔧]` Update Mastra example MCP Server project +- `[maintenance - 🔧]` Update Mastra example MCP server project **Misc** @@ -318,7 +318,7 @@ t **Toolkits** - `[feature - 🚀]` Google Calendar improvements to video call scheduling ([Docs](https://github.com/ArcadeAI/docs/pull/436)) -- `[feature - 🚀]` [MCP Servers/Jira] Added `WhoAmI` tool to Jira, Google, Clickup, Slack, and Zendesk MCP Servers ([Docs](https://github.com/ArcadeAI/docs/pull/426)) +- `[feature - 🚀]` [MCP servers/Jira] Added `WhoAmI` tool to Jira, Google, Clickup, Slack, and Zendesk MCP servers ([Docs](https://github.com/ArcadeAI/docs/pull/426)) **Platform and Engine** @@ -333,7 +333,7 @@ t **Toolkits** -- `[feature - 🚀]` Imgflip MCP Server: tools for memes ([docs PR #424](https://github.com/ArcadeAI/docs/pull/424)) +- `[feature - 🚀]` Imgflip MCP server: tools for memes ([docs PR #424](https://github.com/ArcadeAI/docs/pull/424)) - `[feature - 🚀]` Edit Google Document Tool ([docs PR #427](https://github.com/ArcadeAI/docs/pull/427)) - `[bugfix - 🐛]` [Toolkits/clickup] fix fuzzy match search @@ -355,12 +355,12 @@ t **Toolkits** -- `[feature - 🚀]` Re-add GoogleNews MCP Server +- `[feature - 🚀]` Re-add GoogleNews MCP server **Platform and Engine** -- `[feature - 🚀]` Dashboard: Update MCP Server and tool selection UI in playground -- `[feature - 🚀]` Dashboard: Add MCP Servers and OAuth providers from the design system +- `[feature - 🚀]` Dashboard: Update MCP server and tool selection UI in playground +- `[feature - 🚀]` Dashboard: Add MCP servers and OAuth providers from the design system - `[feature - 🚀]` Dashboard: Add optional request parameters when adding OAuth providers **CLI and TDK** @@ -376,7 +376,7 @@ t ## 2025-08-22 - This week we released a new pricing model for Arcade which will be better for + This week a new pricing model for Arcade was released which will be better for hobbyists and enterprises alike. Learn more here: [https://blog.arcade.dev/pricing-updates](https://blog.arcade.dev/pricing-updates) @@ -396,7 +396,7 @@ t ## 2025-08-15 - This week we enforced a new requirement for all OAuth providers: they must + This week a new requirement for all OAuth providers was enforced: they must have a unique callback URL. This is a minor security change, but does require you to update your OAuth configuration. This can be updated from the dashboard. @@ -418,8 +418,8 @@ t **Misc** -- `[documentation - 📝]` Document Microsoft scopes required by Arcade MCP Servers ([PR #409](https://github.com/ArcadeAI/docs/pull/409)) -- `[documentation - 📝]` Microsoft SharePoint MCP Server documentation ([PR #400](https://github.com/ArcadeAI/docs/pull/400)) +- `[documentation - 📝]` Document Microsoft scopes required by Arcade MCP servers ([PR #409](https://github.com/ArcadeAI/docs/pull/409)) +- `[documentation - 📝]` Microsoft SharePoint MCP server documentation ([PR #400](https://github.com/ArcadeAI/docs/pull/400)) ## 2025-08-08 @@ -427,7 +427,7 @@ t - `[feature - 🚀]` Clickhouse Toolkit ([PR #527](https://github.com/ArcadeAI/arcade-ai/pull/527)) - `[feature - 🚀]` Add search to Google Drive -- `[bugfix - 🐛]` Fix and docstring improvement in MS Teams MCP Server +- `[bugfix - 🐛]` Fix and docstring improvement in MS Teams MCP server **Platform and Engine** @@ -438,12 +438,12 @@ t **Toolkits** -- `[feature - 🚀]` Microsoft Teams MCP Server added +- `[feature - 🚀]` Microsoft Teams MCP server added - `[feature - 🚀]` Jira Toolkit: Add List Sprints & Boards tools -- `[feature - 🚀]` Google Sheets MCP Server: Add pagination to GetSpreadsheet -- `[bugfix - 🐛]` Jira MCP Server: Return UI URL for items again -- `[feature - 🚀]` Salesforce MCP Server: Configure subdomain & max concurrency through secrets -- `[feature - 🚀]` Confluence MCP Server supports Atlassian multi-cloud +- `[feature - 🚀]` Google Sheets MCP server: Add pagination to GetSpreadsheet +- `[bugfix - 🐛]` Jira MCP server: Return UI URL for items again +- `[feature - 🚀]` Salesforce MCP server: Configure subdomain & max concurrency through secrets +- `[feature - 🚀]` Confluence MCP server supports Atlassian multi-cloud **CLI and TDK** @@ -453,11 +453,11 @@ t ## 2025-07-25 - Most Arcade MCP Servers have been removed from the + Most Arcade MCP servers have been removed from the `github.com/ArcadeAI/arcade-ai` repository, and transitioned to closed-source. - Toolkit source code remains available upon request for our paying customers. - This enables us to iterate more quickly and provide a better experience for - our customers. The previously open-sourced MCP Servers are still available in the + Toolkit source code remains available upon request for paying customers. + This enables faster iteration and provides a better experience for + customers. The previously open-sourced MCP servers are still available in the public repository's git history. @@ -487,7 +487,7 @@ t Version 2.0.0 of the Arcade Engine was released this week. Upgrading to version 2.0.0 is recommended for all self-hosted developers, and includes an important security fix for [secure OAuth flows](/guides/user-facing-agents/secure-auth-production). After upgrading, all projects will default to using the Arcade user verifier. If desired, you can then implement a custom user verifier in your application/agent and make the switch via the Arcade Dashboard. -Self-hosed Arcade developers cannot be grandfathered into the old (insecure) behavior of skipping user verification once the Engine is upgraded to version 2.0.0 or higher. +Self-hosted Arcade developers cannot be deprecated into the old (insecure) behavior of skipping user verification once the Engine is upgraded to version 2.0.0 or higher. @@ -516,7 +516,7 @@ Self-hosed Arcade developers cannot be grandfathered into the old (insecure) beh **Misc** -- `[documentation - 📝]` replaced creating MCP Server video with full tutorial ([PR #349](https://github.com/ArcadeAI/docs/pull/349)) +- `[documentation - 📝]` replaced creating MCP server video with full tutorial ([PR #349](https://github.com/ArcadeAI/docs/pull/349)) - `[documentation - 📝]` Add secure/brand auth in production doc ([PR #341](https://github.com/ArcadeAI/docs/pull/341)) ## 2025-07-11 @@ -525,7 +525,7 @@ Self-hosed Arcade developers cannot be grandfathered into the old (insecure) beh **Toolkits** -- `[feature - 🚀]` Split previously combined Google, Microsoft, and other Toolkits into separate MCP Servers to aid in retrieval and maintenance ([PR #438](https://github.com/ArcadeAI/arcade-ai/pull/438)) +- `[feature - 🚀]` Split previously combined Google, Microsoft, and other Toolkits into separate MCP servers to aid in retrieval and maintenance ([PR #438](https://github.com/ArcadeAI/arcade-ai/pull/438)) - `[feature - 🚀]` Slack Toolkit: Major refactor and improvements ([PR #453](https://github.com/ArcadeAI/arcade-ai/pull/453)) **CLI and TDK** @@ -538,13 +538,13 @@ Self-hosed Arcade developers cannot be grandfathered into the old (insecure) beh **Misc** -- `[documentation - 📝]` Document the OAuth scopes required by the Slack MCP Server ([PR #344](https://github.com/ArcadeAI/docs/pull/344)) +- `[documentation - 📝]` Document the OAuth scopes required by the Slack MCP server ([PR #344](https://github.com/ArcadeAI/docs/pull/344)) ## 2025-07-04 **Toolkits** -- `[bugfix - 🐛]` patching MCP Server template generator for outside the main repo ([PR #460](https://github.com/ArcadeAI/arcade-ai/pull/460)) +- `[bugfix - 🐛]` patching MCP server template generator for outside the main repo ([PR #460](https://github.com/ArcadeAI/arcade-ai/pull/460)) - `[bugfix - 🐛]` Filter out unneeded files/directories before deploying workers ([PR #464](https://github.com/ArcadeAI/arcade-ai/pull/464)) **Platform and Engine** @@ -558,38 +558,4 @@ Self-hosed Arcade developers cannot be grandfathered into the old (insecure) beh **Platform and Engine** -- `[feature - 🚀]` Dashboard: Allow editing the description of a secret -- `[feature - 🚀]` Dashboard: Preserve tools when resetting parameters - -## 2025-06-28 - -**Toolkits** - -- `[bugfix - 🐛]` Jira MCP Server: deduplicate cloud data in Atlassian's available-resources response ([PR #456](https://github.com/ArcadeAI/arcade-ai/pull/456)) - -## 2025-06-20 - -**Frameworks** - -- `[feature - 🚀]` Support for OpenAI Agent SDK in Typescript ([docs](/get-started/agent-frameworks/openai-agents/overview) and [example](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts)) - -**Toolkits** - -- `[feature - 🚀]` Jira MCP Server released ([docs](/resources/integrations/productivity/jira)) - -**CLI and TDK** - -- `[feature - 🚀]` V2.0 of Python Tool Development Kit (TDK) -- `[feature - 🚀]` Admin API client support - - Requires v1.6.0 of `arcade-py`, or v1.8.0 of `arcade-js`, or v0.1.0-alpha.4 of `arcade-go` - -**Platform and Engine** - -- `[feature - 🚀]` Admin APIs released for managing users, secrets, and tools ([API References](https://reference.arcade.dev/api-reference#tag/admin)) -- `[bugfix - 🐛]` Unauthenticated MCP servers can be called anonymously -- `[feature - 🚀]` End-user credentials and auth status can be fetched in batches ([docs](/guides/tool-calling/custom-apps/check-auth-status)) - -**Misc** - -- `[feature - 🚀]` Launched Github Discussions for product feedback and support ([link](https://github.com/ArcadeAI/arcade-ai/discussions)) -- `[feature - 🚀]` Launched status.arcade.dev for monitoring platform status ([link](https://status.arcade.dev)) +- `[feature - 🚀]` \ No newline at end of file diff --git a/app/en/resources/glossary/page.mdx b/app/en/resources/glossary/page.mdx index e91f32bac..022a4f21b 100644 --- a/app/en/resources/glossary/page.mdx +++ b/app/en/resources/glossary/page.mdx @@ -5,6 +5,8 @@ description: "Glossary of terms used in the Arcade platform" # Arcade Glossary +This glossary defines key terms used throughout Arcade documentation and the platform. + ## Agents and Tools ```mermaid @@ -15,11 +17,11 @@ graph TD ### Agent -An 'agent' is the intelligent application you are building. It can be a chatbot, a web application, a mobile app, or any other type of application that happens to use an LLM as part of its functionality. Agents interact with the world by calling tools. Helping you build, test, authenticate, and deploy tools is what Arcade is all about. +An agent is the intelligent application you are building. It can be a chatbot, a web application, a mobile app, or any other type of application that happens to use an LLM as part of its capability. Agents interact with the world by calling tools. Helping you build, test, authenticate, and deploy tools is what Arcade is all about. ### Harness -A 'harness' is the application that is running the agent. The agent determines the prompt, the tools, and the policies for every interaction. The harness is the software "glue" that determines _how_ all of these components work together. Are tools called over MCP? Is the OAuth URL opened in a browser? Is the agent able to access bash commands in the terminal? The harness is responsible for handling all of these details. +A harness is the application that runs the agent. The agent determines the prompt, the tools, and the policies for every interaction. The harness is the software "glue" that determines _how_ all of these components work together. Are tools called over MCP? Does the system open OAuth URLs in browsers? Can the agent access bash commands in the terminal? The harness handles all of these details. ### ReAct Agent @@ -27,13 +29,13 @@ This (Reason + Act) is the most common agentic pattern, where an LLM runs in a l ### Context -A 'Context' is an object that is passed to a tool as a parameter when the tool is executed. It contains information about the tool call, the user for which the tool is being called, and any secrets the tool requires to run. +A context is an object that a tool receives as a parameter when the tool executes. It contains information about the tool call, the user for which you call the tool, and any secrets the tool requires to run. _Learn more about [context](/guides/create-tools/tool-basics/runtime-data-access)._ ### Entrypoint File -An 'Entrypoint file' is necessary when building your own MCP servers with Arcade. An entrypoint file creates and runs an `MCPApp` when invoked directly. +An entrypoint file is necessary when building your own MCP servers with Arcade. An entrypoint file creates and runs an `MCPApp` when invoked directly. The following is a minimal example of an entrypoint file: @@ -51,49 +53,49 @@ if __name__ == "__main__": app.run() ``` -### MCP Server +### MCP server -An 'MCP Server' is a collection of tools that can be used by an agent, grouped logically together by a common theme or provider, and the running remote process that serves and executes the tools. MCP Servers are the unit of deployment for tools within Arcade. +An MCP server is a collection of tools that an agent can use, grouped logically together by a common theme or provider, and the running remote process that serves and executes the tools. MCP servers are the unit of deployment for tools within Arcade. -#### Protected MCP Servers +#### Protected MCP servers A protected server implements [MCP authorization](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) and requires the MCP client to provide a token identifying the user when calling the MCP server. Examples: servers that require sign-in, deal with private info, call APIs on your behalf -#### Unprotected MCP Servers +#### Unprotected MCP servers -An unprotected (anonymous) MCP server can be used by any MCP client on the network. Because it is anonymous, it can't identify the user who is using the server. Examples: servers that return static info, weather APIs, etc +An unprotected (anonymous) MCP server allows any MCP client on the network to use it. Because it is anonymous, it can't identify the user who uses the server. Examples: servers that return static info, weather APIs, etc -### Tool +### tool -A 'tool' is a function that can be called by an agent which performs some action - commonly via an API, filesystem, database, etc. Tools are written in Python and deployed by running a worker which contains the MCP Server's code. Tools are defined by the `@tool()` decorator and will be passed `ToolContext` as the first argument. If a tool has dependencies that are not met (a secret is not provided, for example), the tool will fail to execute. +A tool is a function that an agent can call which performs some action - commonly via an API, filesystem, database, etc. tools function with Python and deploy by running a worker which contains the MCP server's code. The `@tool()` decorator defines tools and passes `ToolContext` as the first argument. If a tool has dependencies that fail (when you don't provide a secret, for example), the tool will fail to execute. -Tools are commonly referred to by a qualified name that includes their MCP Server. For example, [Gmail.SendEmail](/resources/integrations/productivity/gmail#gmailsendemail) +tools are commonly referred to by a qualified name that includes their MCP server. For example, [Gmail.SendEmail](/resources/integrations/productivity/gmail#gmailsendemail) _Learn more about [tools](/guides/create-tools/tool-basics/build-mcp-server)._ #### Optimized tools -[Optimized tools](/guides/create-tools/improve/types-of-tools#optimized-tools) are designed from scratch to provide the best performance for LLMs in terms of speed, reliability, accuracy, and cost-effectiveness. +[Optimized tools](/guides/create-tools/improve/types-of-tools#optimized-tools) provide the best performance for LLMs in terms of speed, reliability, accuracy, and cost-effectiveness. #### Unoptimized tools -[Unoptimized tools](/guides/create-tools/improve/types-of-tools#unoptimized-tools) are designed to mirror the original HTTP API design of the upstream service. They are not optimized for LLM usage and are not subject to evaluation suites. We recommend thoroughly evaluating each Unoptimized tool with your Agents or chatbots before using it in production. +[Unoptimized tools](/guides/create-tools/improve/types-of-tools#unoptimized-tools) mirror the original HTTP API design of the upstream service. They are not optimized for LLM usage and are not subject to evaluation suites. Thoroughly evaluate each Unoptimized tool with your Agents or chatbots before using it in production. Understand why [LLMs perform poorly when](/guides/create-tools/improve/types-of-tools#why-llms-perform-poorly when-calling-http-apis) calling HTTP APIs. -### Tool Context +### Tool context -'Tool context' is an object that is passed to a tool as a parameter when the tool is executed. It contains information about the tool call, the user for which the tool is being called, and any secrets the tool requires to run. +A tool context is an object that the system passes to a tool as a parameter when the tool executes. It contains information about the tool call, the user for which you call the tool, and any secrets the tool requires to run. _Learn more about [tool context](/guides/create-tools/tool-basics/runtime-data-access)._ -### Transport Modes +### Transport modes -MCP servers can communicate with clients through different transport mechanisms. Each transport is optimized for specific use cases and client types. +MCP servers can communicate with clients through different transport mechanisms. Each transport optimizes for specific use cases and client types. -The stdio (standard input/output) transport is used for direct client connections. It is ideal for desktop applications (Claude, VS Code, Cursor) and command-line tools. +The stdio (standard input/output) transport connects to clients directly. It is ideal for desktop applications (Claude, VS Code, Cursor) and command-line tools. -The HTTP transport provides REST/SSE endpoints for web-based clients. It is the default transport mode and is used for most clients. +The HTTP transport provides REST/SSE endpoints for web-based clients. It is the default transport mode and serves most clients. _Learn more about [transport modes in the MCP Protocol documentation](https://modelcontextprotocol.info/docs/concepts/transports/)._ @@ -101,9 +103,9 @@ _Learn more about [transport modes in the MCP Protocol documentation](https://mo MCP is an open standard protocol that enables LLMs to access and use tools and data sources. Arcade tools go further than MCP with enterprise-grade authentication, secure token management, and fine-grained permissions. This allows your tools to be accessible to any LLM that supports MCP, while maintaining security and user privacy. -Arcade Tools can be presented as an MCP server (via the Arcade Engine), allowing any LLM that supports MCP to access your tools. In the future, you will be able to add remote MCP servers to your project as additional workers, making their tools available to your agents. +The system can present Arcade tools as an MCP server (via the Arcade Engine), allowing any LLM that supports MCP to access your tools. In the future, you will be able to add remote MCP servers to your project as additional workers, making their tools available to your agents. -## The Arcade Platform +## The Arcade platform ```mermaid graph TD @@ -116,25 +118,25 @@ graph TD ### Account -The 'account' is you (or your teammates), the developer(s) who are using Arcade to build an application or agent. You can sign into the Arcade dashboard, manage projects, and more. +The account is you (or your teammates), the developers who use Arcade to build an application or agent. You can sign in to the Arcade dashboard, manage projects, and more. ### Tenant -A 'tenant' is a collection of projects with unified billing details. It is the top-level unit of organization in Arcade. You can be a member of one or more tenants, and each tenant can have multiple projects. +A tenant is a collection of projects with unified billing details. It is the top-level unit of organization in Arcade. You can be a member of one or more tenants, and each tenant can have multiple projects. ### Project -A 'project' is a collection of agents and tools. It is smallest unit of organization and isolation in Arcade. You can have multiple projects, and each project can have multiple agents and tools. Accounts can be members of multiple projects, and each project will have different API keys. +A project is a collection of agents and tools. It is smallest unit of organization and isolation in Arcade. You can have multiple projects, and each project can have multiple agents and tools. Accounts can be members of multiple projects, and each project will have different API keys. ### Arcade API -The 'Arcade API' is a set of endpoints that allow you to interact with the Arcade platform. You can use the API to call tools, get tool definitions, manage user auth, and more. See the [Arcade API Reference](/references/api) for more details. +The Arcade API is a set of endpoints that allow you to interact with the Arcade platform. You can use the API to call tools, get tool definitions, manage user authorization, and more. See the [Arcade API Reference](/references/api) for more details. -### API Key +### API key -An 'API key' is a secret key that is used to authenticate requests to the Arcade API. It is used to identify the project that the request is for. API keys are project-specific. +An API key is a secret key that authenticates requests to the Arcade API. It identifies the project that the request is for. API keys are project-specific. -## Authentication and Billing +## Authentication and billing ```mermaid graph TD @@ -144,47 +146,47 @@ graph TD ### User -A 'user' is your end-user, the person who is using your application or agent. Users are counted by the unique `user_id` properties sent when calling tools. `user_id` values are commonly email addresses, but can be any string or number. +A user is your end-user, the person who uses your application or agent. The system counts users by the unique `user_id` properties sent when calling tools. `user_id` values are commonly email addresses, but can be any string or number. ### Monthly Active Users (MAU) -Monthly Active Users are the unique end-users (counted by `user_id`) who have executed a tool in your app/agent within the past month. If the same `user_id` calls a tool multiple times in the same month, or executes multiple tools, that `user_id` is only counted once when calculating MAU. +Monthly Active Users are the unique end-users (counted by `user_id`) who have executed a tool in your app/agent within the past month. If the same `user_id` calls a tool multiple times in the same month, or executes multiple tools, the system counts that `user_id` only once when calculating MAU. -### User Challenges +### User challenges -User Challenges are the count of authorizations performed for any user (specified by `user_id` in Arcade's SDKs and APIs). Authorization challenges occur when a user needs a new permission or scope that they don't currently have, including previously-held scopes that were deleted or expired. The same user authenticating to multiple MCP Servers will have a User Challenge for each MCP Server (e.g. once for Slack and once for Google). We also count the act of elevating permissions to a user who has already authenticated to a MCP Server (e.g. adding a "write" scope when they previously only had a "read" scope). +User challenges count the authorizations performed for any user (specified by `user_id` in Arcade's SDKs and APIs). Authorization challenges occur when a user needs a new permission or scope that they don't currently have, including previously held scopes that expired or were deleted. The same user authenticating to multiple MCP servers will have a user challenge for each MCP server (for example once for Slack and once for Google). This also counts elevating permissions for a user who has already authenticated to a MCP server (for example adding a "write" scope when they previously only had a "read" scope). -### Auth Provider +### auth provider -An 'auth provider' is a service that your users sign in with to let the agent access their data or take actions on their behalf. This can be a hosted service like Google or Slack, or a custom OAuth provider. Multiple MCP Servers may share the same auth provider (for example, Gmail and Google Drive both use Google's OAuth provider). Custom auth providers are defined in the Arcade Dashboard, or in your Engine YAML if you're self-hosting. +An auth provider is a service that your users sign in with to let the agent access their data or take actions on their behalf. This can be a hosted service like Google or Slack, or a custom OAuth provider. Multiple MCP servers may share the same auth provider (for example, Gmail and Google Drive both use Google's OAuth provider). The system defines custom auth providers in the Arcade Dashboard, or in your Engine YAML if you're self-hosting. _Learn more about [auth providers](/references/auth-providers)._ -### Authorization Scope +### Authorization scope -An 'authorization scope' is a permission that a user can grant to an agent. This is used to control what the agent can do with the user's data. Available authorization scopes are defined by the authentication provider, and each tool defines the scopes it requires. +An authorization scope is a permission that a user can grant to an agent. This controls what the agent can do with the user's data. The authentication provider defines available authorization scopes, and each tool defines the scopes it requires. Learn more about [authorized tool calling](/guides/tool-calling/custom-apps/auth-tool-calling). -### Tool Executions +### Tool executions -A 'tool execution' is a single call to a tool to interact with a remote system or service. The tool execution itself may fail (e.g. the user does not have permission to call the tool), but as long as the execution was able to be routed to a worker, it will be counted. +A tool execution is a single call to a tool to interact with a remote system or service. The tool execution itself may fail (for example the user does not have permission to call the tool), but as long as the system can route the execution to a worker, it will count the execution. _Learn more about [tool executions](/guides/tool-calling)._ -### Standard and Pro Tool executions +### Standard and Pro tool executions -Arcade tools are divided into 2 categories: Standard and Pro. While all tools have some cost for Arcade to run, Pro tools are significantly more costly - either due to infrastructure costs, the complexity of the tool, or a cost imposed by the provider of the tool. Pro tools cost more to execute and have different limits. +The system divides Arcade tools into 2 categories: Standard and Pro. While all tools have some cost for Arcade to run, Pro tools cost considerably more - either due to infrastructure costs, the complexity of the tool, or a cost imposed by the provider of the tool. Pro tools cost more to execute and have different limits. Learn more about tool pricing [here](https://www.arcade.dev/pricing). ### Bring Your Own Credentials (BYOC) -Bring Your Own Credentials (BYOC) is a feature that allows you to use your own credentials to certain pro tools. This changes the cost of the tool execution, as you will be charged directly by the provider of the tool, rather than relying on Arcade to pay the bill for you. +Bring Your Own Credentials (BYOC) is a feature that allows you to use your own credentials to certain pro tools. This changes the cost of the tool execution, as you will incur direct charges from the provider of the tool, rather than relying on Arcade to pay the bill for you. To set your own credentials, set the requisite secret within the Arcade Dashboard, overwriting the default 'static' credentials. -## Tool Execution and Tool Development +## Tool execution and tool development ```mermaid graph TD @@ -194,28 +196,28 @@ graph TD D --> E[MCP Server] ``` -### Arcade Client +### Arcade client -The 'Arcade client' is the SDK that you use to interact with the Arcade platform. It is how your agent lists and calls tools, tied back to your project via an API key. We offer clients for many popular languages and frameworks, including Python, JavaScript, and more. +The Arcade client is the SDK that you use to interact with the Arcade platform. It is how your agent lists and calls tools, tied back to your project via an API key. Arcade offers clients for many popular languages and frameworks, including Python, JavaScript, and more. _Learn more about [the Arcade clients](/references)._ ### Arcade Engine -The Arcade Engine is the core of the Arcade platform. It is responsible for routing tool execution requests to the correct MCP server, managing the lifecycle of tool executions, and for enforcing security and authorization decisions. +The Arcade Engine is the core of the Arcade platform. It routes tool execution requests to the correct MCP server, manages the lifecycle of tool executions, and enforces security and authorization decisions. -The Arcade Engine is also responsible for the OAuth flow for your agent's users. This includes granting and elevating permissions and keeping tokens fresh. +The Arcade Engine also handles the OAuth flow for your agent's users. This includes granting and elevating permissions and keeping tokens fresh. -### MCP Gateway +### MCP gateway -MCP Gateways are a feature of the Arcade Engine that allows you to add and combine multiple MCP servers in your project. It allows your clients to speak MCP directly to Arcade and get all the functionality you'd expect from the Arcade Engine. The MCP Gateway is responsible for routing tool execution requests to the correct MCP server, and for enforcing security and authorization decisions. You can mix and match tools from different MCP servers in the same project, and not all tools from a MCP server need to be available to the same agent or LLM. +MCP gateways are a feature of the Arcade Engine that allows you to add and combine multiple MCP servers in your project. It allows your clients to speak MCP directly to Arcade and get all the capability you'd expect from the Arcade Engine. The MCP gateway routes tool execution requests to the correct MCP server, and enforces security and authorization decisions. You can mix and match tools from different MCP servers in the same project, and not all tools from a MCP server need to be available to the same agent or LLM. ### Arcade MCP (Server Development Kit) -Arcade MCP is the secure framework for building MCP servers. It is responsible for the lifecycle of tool executions, and for enforcing security and authorization decisions within the boundary of the server. +Arcade MCP is the secure framework for building MCP servers. It manages the lifecycle of tool executions, and enforces security and authorization decisions within the boundary of the server. ### Evaluations (Evals) -Evaluations are a way to test the LLMs' ability to select and call your tools. Arcade's eval suite can and should be run as part of the development process to ensure your tools are working as expected. +Evaluations test the LLMs' ability to select and call your tools. You can and should run Arcade's eval suite as part of the development process to ensure your tools work as expected. -_Learn more about evaluations [here](/guides/create-tools/evaluate-tools/why-evaluate)._ +_Learn more about evaluations [here](/guides/create-tools/evaluate-tools/why-evaluate)._ \ No newline at end of file