From 18b9dc0eba77358716fd49553f264441683c68e8 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 4 Dec 2025 16:22:36 -0800 Subject: [PATCH 01/11] updating sidebar to reflect mockup navigation --- app/en/_meta.tsx | 5 +- app/en/home/_meta.tsx | 400 ++++++++++++++++-- .../home/calling-tools-custom-apps/page.mdx | 20 + app/en/home/configure-arcade/page.mdx | 27 ++ app/en/home/create-projects/page.mdx | 27 ++ app/en/home/create-tenants/page.mdx | 26 ++ app/en/home/dashboard/page.mdx | 28 ++ app/en/home/mcp-gateway-quickstart/page.mdx | 25 ++ app/en/home/python-quickstart/page.mdx | 38 ++ app/en/home/sample-agents/page.mdx | 26 ++ app/en/home/tool-calling-intro/page.mdx | 31 ++ app/en/home/when-build-tools/page.mdx | 34 ++ 12 files changed, 643 insertions(+), 44 deletions(-) create mode 100644 app/en/home/calling-tools-custom-apps/page.mdx create mode 100644 app/en/home/configure-arcade/page.mdx create mode 100644 app/en/home/create-projects/page.mdx create mode 100644 app/en/home/create-tenants/page.mdx create mode 100644 app/en/home/dashboard/page.mdx create mode 100644 app/en/home/mcp-gateway-quickstart/page.mdx create mode 100644 app/en/home/python-quickstart/page.mdx create mode 100644 app/en/home/sample-agents/page.mdx create mode 100644 app/en/home/tool-calling-intro/page.mdx create mode 100644 app/en/home/when-build-tools/page.mdx diff --git a/app/en/_meta.tsx b/app/en/_meta.tsx index 691941933..2aea69066 100644 --- a/app/en/_meta.tsx +++ b/app/en/_meta.tsx @@ -6,16 +6,19 @@ const meta: MetaRecord = { copyPage: false, }, }, + // 1.0 Home Section home: { type: "page", title: "Home", - href: "/get-started", + href: "/home", }, + // MCP Servers Section "mcp-servers": { type: "page", title: "MCP Servers", href: "/mcp-servers", }, + // API & SDKs Section references: { type: "page", title: "API & SDKs", diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index ff7c4d069..a2dbc4b7f 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -35,85 +35,401 @@ export const meta: MetaRecord = { title: Arcade.dev, href: "https://arcade.dev", }, - "-- Getting Started": { + "-- Getting Started with tool calling": { type: "separator", - title: "Using Arcade", + title: "Getting Started with tool calling", }, - quickstart: { - title: "Hosted Tools Quickstart", - }, - "custom-mcp-server-quickstart": { - title: "Build MCP Server QuickStart", + "calling-tools-custom-apps": { + title: "Calling tools in your custom apps", + href: "/calling-tools-custom-apps", }, "api-keys": { - title: "Get an API key", + title: "Get an API Key", + }, + "mcp-gateway-quickstart": { + title: "Calling tools in 3rd party agents, apps, or IDEs", + href: "/mcp-gateway-quickstart", + }, + "mcp-server-quickstart": { + title: "Build MCP Server to write custom tools", + href: "/mcp-server-quickstart", + }, + "sample-agents": { + title: "Sample agents with tool calling", + href: "/sample-agents", + }, + "configure-arcade": { + title: "Configure Arcade", + href: "/configure-arcade", + }, + "overview-updated": { + title: "Overview", + href: "/overview-updated", + }, + dashboard: { + title: "Dashboard", + href: "/dashboard", + }, + "create-tenants": { + title: "Create Tenants", + href: "/create-tenants", + }, + "create-projects": { + title: "Create Projects", + href: "/create-projects", + }, + "arcade-cli": { + title: "Using Arcade's CLI", + href: "/arcade-cli", + }, + "security-compliance": { + title: "Security & Compliance", + href: "/security-compliance", + }, + "identity-providers": { + title: "Supported Identity Providers", + href: "/identity-providers", }, - "-- Authoring Tools": { + "soc-2": { + title: "SOC-2", + href: "/soc-2", + }, + "enterprise-sso": { + title: "Enterprise Single Sign On", + href: "/enterprise-sso", + }, + "rbac-config": { + title: "Configuring Role Based Access Control for your organization", + href: "/rbac-config", + }, + "-- Tool Calling": { + type: "separator", + title: "Tool Calling", + }, + "tool-calling-intro": { + title: "Introduction", + href: "/tool-calling-intro", + }, + "error-handling": { + title: "Error Handling", + href: "/error-handling", + }, + "third-party-apps": { type: "separator", - title: "Authoring Tools", + title: "In 3rd party applications", + }, + "mcp-gateway-quickstart-2": { + title: "Calling tools in 3rd party agents, apps, or IDEs", + href: "/mcp-gateway-quickstart", + }, + "mcp-clients": { + title: "Connecting to a MCP Client", + }, + "cursor-client": { + title: "Cursor", + href: "/cursor-client", + }, + "claude-desktop": { + title: "Claude Desktop", + href: "/claude-desktop", + }, + "vscode-client": { + title: "Visual Studio Code", + href: "/vscode-client", + }, + "evaluation-suite": { + title: "Creating an evaluation suite to test tools", + href: "/evaluation-suite", + }, + "custom-apps": { + type: "separator", + title: "In custom applications", + }, + "calling-tools-custom-apps-2": { + title: "Calling tools in your custom apps", + href: "/calling-tools-custom-apps", + }, + "authorized-tool-calling": { + title: "Authorized Tool Calling", + href: "/authorized-tool-calling", + }, + "auth-status-check": { + title: "Checking Authorization Status", + href: "/auth-status-check", + }, + "tool-formats": { + title: "Tool formats", + href: "/tool-formats", + }, + "connect-arcade-llm": { + title: "Connecting Arcade tools to your LLM", + href: "/connect-arcade-llm", + }, + "test-tool-performance": { + title: "Testing tool performance", + href: "/test-tool-performance", + }, + triggers: { + type: "separator", + title: "Triggers", + }, + "background-agents": { + title: "Set up a background agent using events", + href: "/background-agents", + }, + "scheduled-executions": { + title: "Set up scheduled tool executions", + href: "/scheduled-executions", + }, + "direct-api-call": { + title: "Direct Third-Party API Call", + href: "/direct-api-call", + }, + "-- Tool Writing": { + type: "separator", + title: "Tool Writing", + }, + "learn-basics": { + type: "separator", + title: "Learn the basics", + }, + "when-build-tools": { + title: "When to build tools", + href: "/when-build-tools", + }, + "compare-server-types": { + title: "Compare Server Types", }, "build-tools": { - title: "Build tools", + title: "Build MCP Server to write custom tools", + }, + "create-tool-auth": { + title: "Create a tool with auth", + href: "/create-tool-auth", + }, + "create-tool-secrets": { + title: "Create a tool with secrets", + href: "/create-tool-secrets", + }, + "runtime-data-access": { + title: "Accessing runtime data", + href: "/runtime-data-access", + }, + "call-tools-mcp": { + title: "Call tools from MCP clients", + href: "/call-tools-mcp", }, "evaluate-tools": { - title: "Evaluate tools", + title: "Create an evaluation suite", + }, + "run-evaluations": { + title: "Run evaluations", + href: "/run-evaluations", + }, + "improve-performance": { + type: "separator", + title: "Building tools to get more performance out of existing toolkits", + }, + "types-of-tools": { + title: "Types of tools", + href: "/types-of-tools", + }, + "eval-starter-tools": { + title: "Write eval to assess combo of starter tools", + href: "/eval-starter-tools", + }, + "custom-tool-improvements": { + title: "Write custom tool that improves on relevant Starter tools", + href: "/custom-tool-improvements", + }, + "run-evaluations-2": { + title: "Run evaluations", + href: "/run-evaluations", }, "serve-tools": { - title: "Serve tools", + title: "Arcade Deploy", }, - "-- Agent Frameworks and MCP": { + "new-functionality": { type: "separator", - title: "Agent Frameworks and MCP", + title: "Building tools with agent functionality that doesn't exist", }, - "mcp-clients": { - title: "MCP Clients", + "eval-new-functionality": { + title: "Write eval for functionality you want", + href: "/eval-new-functionality", + }, + "custom-toolkit": { + title: "Write custom toolkit", + href: "/custom-toolkit", + }, + "arcade-deploy-2": { + title: "Arcade Deploy", + href: "/arcade-deploy", + }, + "newest-models": { + type: "separator", + title: "Ensure tools work with the newest models", + }, + "run-eval-new-model": { + title: "Run existing eval and observe outcome with new model", + href: "/run-eval-new-model", + }, + "modify-tool-new-model": { + title: "Modify tool to work well with new model", + href: "/modify-tool-new-model", + }, + "tool-writing-reference": { + type: "separator", + title: "Reference", + }, + "organize-mcp-tools": { + title: "Organize MCP server tools", + href: "/organize-mcp-tools", + }, + "useful-tool-errors": { + title: "Providing useful tool errors", + href: "/useful-tool-errors", + }, + "retry-tools": { + title: "Retry tools with improved prompt", + href: "/retry-tools", + }, + "migrate-toolkits": { + title: "Migrate from toolkits to MCP Servers", + href: "/migrate-toolkits", + }, + "why-evaluate": { + title: "Why evaluate tools?", + href: "/why-evaluate", + }, + "-- Configuring Arcade with Agent Orchestrators": { + type: "separator", + title: "Configuring Arcade with Agent Orchestrators", + }, + "orchestrator-overview": { + title: + "Overview to route based on language / orchestration framework combo", + href: "/orchestrator-overview", + }, + "python-quickstart": { + title: "Python Quickstart", + href: "/python-quickstart", + }, + "typescript-quickstart": { + title: "Typescript Quickstart", + href: "/typescript-quickstart", }, langchain: { - title: "LangChain", + title: "LangGraph", + }, + "langgraph-python": { + title: "Quickstart (Python)", + href: "/langgraph-python", + }, + "langgraph-typescript": { + title: "Quickstart (Typescript)", + href: "/langgraph-typescript", + }, + "langgraph-tools": { + title: "Using LangGraph tools", + href: "/langgraph-tools", + }, + "oai-agents": { + title: "OpenAI Agents", + }, + "openai-python": { + title: "Quickstart (Python)", + href: "/openai-python", + }, + "openai-typescript": { + title: "Quickstart (Typescript)", + href: "/openai-typescript", }, crewai: { title: "CrewAI", }, + "crewai-python": { + title: "Quickstart (Python)", + href: "/crewai-python", + }, + "crewai-typescript": { + title: "Quickstart (Typescript)", + href: "/crewai-typescript", + }, + "crewai-custom-auth": { + title: "Custom auth flow", + href: "/crewai-custom-auth", + }, + "open-agents": { + title: "OpenAgents", + href: "/open-agents", + }, + "openagents-python": { + title: "Quickstart (Python)", + href: "/openagents-python", + }, "google-adk": { title: "Google ADK", }, + "google-adk-python": { + title: "Quickstart (Python)", + href: "/google-adk-python", + }, + "google-adk-typescript": { + title: "Quickstart (Typescript)", + href: "/google-adk-typescript", + }, mastra: { title: "Mastra", }, - "oai-agents": { - title: "OpenAI Agents", + "mastra-typescript": { + title: "Quickstart (Typescript)", + href: "/mastra-typescript", }, vercelai: { title: "Vercel AI", }, - "-- Core Concepts": { + "vercelai-typescript": { + title: "Quickstart (Typescript)", + href: "/vercelai-typescript", + }, + "-- Scaling your app to many end-users": { type: "separator", - title: "Core Concepts", + title: "Scaling your app to many end-users", }, - "use-tools": { - title: "Tool Calling", + "multi-user-auth": { + title: "Set-up secure multi-user auth for your app", + href: "/multi-user-auth", }, - auth: { - title: "Authorization", + "auth-providers": { + title: "Customizing Auth", }, - "mcp-gateways": { - title: "MCP Gateways", + "auth-overview": { + title: "Overview", + href: "/auth-overview", }, - "arcade-cli": { - title: "Arcade CLI", + oauth2: { + title: "OAuth 2.0", + href: "/oauth2", }, - "-- Hosting options": { + "-- Hosting Options": { type: "separator", - title: "Hosting options", + title: "Hosting Options", }, "hosting-overview": { title: "Overview", + href: "/hosting-overview", }, - deployment: { - title: "Deployment", + "cloud-infrastructure": { + title: "Using Arcade's Cloud Infrastructure", + href: "/cloud-infrastructure", }, - "auth-providers": { - title: "Customizing Auth", + "on-premise-mcp": { + title: "Using On-premise MCP Servers", + href: "/on-premise-mcp", + }, + "engine-config": { + title: "Engine configuration", + href: "/engine-config", }, "-- Guides": { type: "separator", @@ -125,18 +441,16 @@ export const meta: MetaRecord = { faq: { title: "FAQ", }, - "compare-server-types": { - title: "Compare Server Types", - }, - "agentic-development": { - title: "Agentic Development", + "connect-docs-ide": { + title: "Connect Arcade Docs to Your IDE", + href: "/connect-docs-ide", }, changelog: { title: "Changelog", }, - "-- Registry": { + "-- Tool Registry": { type: "separator", - title: "Registry", + title: "Tool Registry", }, "registry-early-access": { title: "Registry Early Access", diff --git a/app/en/home/calling-tools-custom-apps/page.mdx b/app/en/home/calling-tools-custom-apps/page.mdx new file mode 100644 index 000000000..ac2fb8f44 --- /dev/null +++ b/app/en/home/calling-tools-custom-apps/page.mdx @@ -0,0 +1,20 @@ +# Calling Tools in Your Custom Apps + +This is a placeholder page for calling tools in your custom applications. + +## Overview + +Learn how to integrate Arcade tools into your custom applications for enhanced functionality. + +## Key Concepts + +- Tool integration patterns +- Authentication handling +- Error management +- Performance optimization + +## Next Steps + +- [Get an API Key](/en/home/api-keys) +- [Tool Calling Introduction](/en/home/tool-calling-intro) +- [Connect Arcade tools to your LLM](/en/home/connect-arcade-llm) \ No newline at end of file diff --git a/app/en/home/configure-arcade/page.mdx b/app/en/home/configure-arcade/page.mdx new file mode 100644 index 000000000..f80033e6c --- /dev/null +++ b/app/en/home/configure-arcade/page.mdx @@ -0,0 +1,27 @@ +# Configure Arcade + +This is a placeholder page for configuring Arcade. + +## Overview + +Learn how to set up and configure Arcade for your organization's needs. + +## Configuration Areas + +- Dashboard settings +- Tenant management +- Project configuration +- Security settings + +## Getting Started + +1. Access the Arcade Dashboard +2. Create your organization +3. Set up projects and tenants +4. Configure authentication + +## Advanced Configuration + +- Enterprise SSO +- Role-based access control +- Custom authentication providers \ No newline at end of file diff --git a/app/en/home/create-projects/page.mdx b/app/en/home/create-projects/page.mdx new file mode 100644 index 000000000..d1f49a43c --- /dev/null +++ b/app/en/home/create-projects/page.mdx @@ -0,0 +1,27 @@ +# Create Projects + +This is a placeholder page for creating projects in Arcade. + +## Overview + +Learn how to create and manage projects within your Arcade organization. + +## Project Structure + +Projects help organize your tools, configurations, and team access within Arcade. + +## Creating a Project + +1. Access the Arcade Dashboard +2. Navigate to Projects +3. Click "New Project" +4. Configure project settings +5. Invite team members + +## Project Settings + +- Project name and description +- Tool configurations +- Team permissions +- Environment variables +- API keys and secrets \ No newline at end of file diff --git a/app/en/home/create-tenants/page.mdx b/app/en/home/create-tenants/page.mdx new file mode 100644 index 000000000..adedd4596 --- /dev/null +++ b/app/en/home/create-tenants/page.mdx @@ -0,0 +1,26 @@ +# Create Tenants + +This is a placeholder page for creating tenants in Arcade. + +## Overview + +Learn how to create and manage tenants for multi-user applications. + +## What are Tenants? + +Tenants allow you to isolate data and configurations for different organizations or user groups within your application. + +## Creating a Tenant + +1. Navigate to the Dashboard +2. Go to the Tenants section +3. Click "Create New Tenant" +4. Configure tenant settings +5. Set up authentication + +## Tenant Configuration + +- Tenant name and description +- Authentication settings +- Tool access permissions +- Usage limits and quotas \ No newline at end of file diff --git a/app/en/home/dashboard/page.mdx b/app/en/home/dashboard/page.mdx new file mode 100644 index 000000000..2d149b9b6 --- /dev/null +++ b/app/en/home/dashboard/page.mdx @@ -0,0 +1,28 @@ +# Dashboard + +This is a placeholder page for the Arcade Dashboard overview. + +## Overview + +Overview of various Dashboard tabs and jobs to be done. + +## Dashboard Sections + +### Projects Tab +Manage your Arcade projects and their configurations. + +### Tools Tab +Browse and manage your available tools and toolkits. + +### Analytics Tab +Monitor usage, performance, and tool calling metrics. + +### Settings Tab +Configure organization settings, authentication, and integrations. + +## Getting Started + +1. Log into the Arcade Dashboard +2. Create your first project +3. Configure your tools +4. Monitor usage and performance \ No newline at end of file diff --git a/app/en/home/mcp-gateway-quickstart/page.mdx b/app/en/home/mcp-gateway-quickstart/page.mdx new file mode 100644 index 000000000..28d4b7d4b --- /dev/null +++ b/app/en/home/mcp-gateway-quickstart/page.mdx @@ -0,0 +1,25 @@ +# MCP Gateway Quickstart + +This is a placeholder page for the MCP Gateway quickstart guide. + +## Overview + +Learn how to call tools in 3rd party agents, apps, or IDEs using the MCP Gateway. + +## Prerequisites + +- Arcade API key +- Supported MCP client + +## Setup Steps + +1. Configure your MCP Gateway +2. Connect to your client application +3. Test tool calling functionality + +## Supported Clients + +- Cursor +- Claude Desktop +- Visual Studio Code +- Other MCP-compatible applications \ No newline at end of file diff --git a/app/en/home/python-quickstart/page.mdx b/app/en/home/python-quickstart/page.mdx new file mode 100644 index 000000000..04ef6b4c2 --- /dev/null +++ b/app/en/home/python-quickstart/page.mdx @@ -0,0 +1,38 @@ +# Python Quickstart + +This is a placeholder page for the Python quickstart guide. + +## Overview + +Get started with Arcade tools in Python applications quickly and easily. + +## Prerequisites + +- Python 3.8 or higher +- Arcade API key +- Virtual environment (recommended) + +## Installation + +```bash +pip install arcade-ai +``` + +## Quick Setup + +```python +import arcade + +# Initialize the client +client = arcade.Arcade(api_key="your-api-key") + +# Call a tool +result = client.tools.call("example-tool", {"param": "value"}) +print(result) +``` + +## Next Steps + +- [Tool Calling Introduction](/en/home/tool-calling-intro) +- [Authorized Tool Calling](/en/home/authorized-tool-calling) +- [Error Handling](/en/home/error-handling) \ No newline at end of file diff --git a/app/en/home/sample-agents/page.mdx b/app/en/home/sample-agents/page.mdx new file mode 100644 index 000000000..454b662a9 --- /dev/null +++ b/app/en/home/sample-agents/page.mdx @@ -0,0 +1,26 @@ +# Sample Agents with Tool Calling + +This is a placeholder page for sample agents with tool calling examples. + +## Overview + +Explore a suite of example agents you can duplicate and build off of for your custom applications. + +## Available Examples + +- Customer support agent +- Data analysis agent +- Content creation agent +- Task automation agent + +## Getting Started + +Each sample agent includes: +- Complete source code +- Setup instructions +- Tool configuration +- Deployment guidelines + +## Template Repository + +Find all sample agents in our GitHub repository with ready-to-deploy examples. \ No newline at end of file diff --git a/app/en/home/tool-calling-intro/page.mdx b/app/en/home/tool-calling-intro/page.mdx new file mode 100644 index 000000000..749e2f6f9 --- /dev/null +++ b/app/en/home/tool-calling-intro/page.mdx @@ -0,0 +1,31 @@ +# Tool Calling Introduction + +This is a placeholder page for an introduction to tool calling. + +## Overview + +Learn the fundamentals of tool calling with Arcade and how it enhances AI applications. + +## What is Tool Calling? + +Tool calling allows AI models to interact with external systems and APIs to perform actions beyond text generation. + +## Key Concepts + +- **Tools**: Functions that can be called by AI models +- **Schemas**: Descriptions of tool parameters and return values +- **Authorization**: Managing access to authenticated tools +- **Context**: Runtime data passed to tools + +## Benefits + +- Extend AI capabilities beyond text +- Connect to real-world systems +- Perform actions on behalf of users +- Access live data and services + +## Next Steps + +- [Error Handling](/en/home/error-handling) +- [Tool Formats](/en/home/tool-formats) +- [Authorized Tool Calling](/en/home/authorized-tool-calling) \ No newline at end of file diff --git a/app/en/home/when-build-tools/page.mdx b/app/en/home/when-build-tools/page.mdx new file mode 100644 index 000000000..8e61729ae --- /dev/null +++ b/app/en/home/when-build-tools/page.mdx @@ -0,0 +1,34 @@ +# When to Build Tools + +This is a placeholder page about when to build custom tools. + +## Overview + +Overview page to direct to the various scenarios in which you'd build a tool. + +## Scenarios for Building Tools + +### New Functionality +Build tools when you need agent functionality that doesn't exist in current toolkits. + +### Performance Optimization +Create custom tools to get more performance from existing agent capabilities. + +### Model Compatibility +Update tools to work with the newest language models and their capabilities. + +### Integration Requirements +Build tools for specific APIs or systems not covered by existing toolkits. + +## Decision Framework + +1. **Evaluate existing tools** - Check if current tools meet your needs +2. **Assess performance** - Determine if custom tools would improve results +3. **Consider maintenance** - Factor in ongoing support requirements +4. **Plan for testing** - Create evaluation suites for new tools + +## Next Steps + +- [Compare Server Types](/en/home/compare-server-types) +- [Build MCP Server](/en/home/build-tools) +- [Create Evaluation Suite](/en/home/evaluate-tools) \ No newline at end of file From 0eab92fa8824d01c4830f12e40450a7dca01a8f8 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 4 Dec 2025 16:56:26 -0800 Subject: [PATCH 02/11] adding all the sidebar items --- app/en/home/_meta.tsx | 284 +------- app/en/home/agentic-development/page.mdx | 26 - app/en/home/arcade-cli/page.mdx | 413 ----------- app/en/home/auth/_meta.tsx | 7 - app/en/home/auth/auth-tool-calling/page.mdx | 163 ----- .../call-third-party-apis-directly/page.mdx | 215 ------ app/en/home/auth/how-arcade-helps.mdx | 78 -- app/en/home/auth/how-arcade-helps/page.mdx | 78 -- .../home/auth/secure-auth-production/page.mdx | 219 ------ app/en/home/auth/tool-auth-status/page.mdx | 207 ------ app/en/home/build-tools/_meta.tsx | 11 - .../call-tools-from-mcp-clients/page.mdx | 323 -------- .../build-tools/create-a-mcp-server/page.mdx | 326 --------- .../create-a-tool-with-auth/page.mdx | 338 --------- .../create-a-tool-with-secrets/page.mdx | 295 -------- .../migrate-from-toolkits/page.mdx | 301 -------- .../organize-mcp-server-tools/page.mdx | 208 ------ .../providing-useful-tool-errors/page.mdx | 231 ------ .../retry-tools-with-improved-prompt/page.mdx | 84 --- app/en/home/build-tools/tool-context/page.mdx | 296 -------- app/en/home/compare-server-types/page.mdx | 17 - .../home/configure-arcade-section/_meta.tsx | 7 + .../arcade-cli-section/page.mdx | 7 + .../create-projects-section/page.mdx | 7 + .../create-tenants-section/page.mdx | 7 + .../dashboard-section/page.mdx | 7 + .../overview-updated/page.mdx | 7 + app/en/home/configure-arcade/page.mdx | 27 - app/en/home/create-projects/page.mdx | 27 - app/en/home/create-tenants/page.mdx | 26 - app/en/home/crewai/_meta.tsx | 7 +- app/en/home/crewai/quickstart-python/page.mdx | 7 + .../crewai/quickstart-typescript/page.mdx | 7 + app/en/home/crewai/use-arcade-tools/page.mdx | 148 ---- app/en/home/custom-apps/_meta.tsx | 8 + .../custom-apps/auth-status-check/page.mdx | 7 + .../authorized-tool-calling/page.mdx | 7 + .../calling-tools-custom-apps-2/page.mdx | 7 + .../custom-apps/connect-arcade-llm/page.mdx | 7 + .../test-tool-performance/page.mdx | 7 + app/en/home/custom-apps/tool-formats/page.mdx | 7 + .../custom-mcp-server-quickstart/page.mdx | 274 ------- app/en/home/dashboard/page.mdx | 28 - app/en/home/deployment/_meta.tsx | 22 - .../deployment/arcade-cloud-infra/page.mdx | 28 - .../deployment/engine-configuration/page.mdx | 689 ------------------ app/en/home/deployment/on-prem-mcp/page.mdx | 320 -------- app/en/home/evaluate-tools/_meta.tsx | 5 - .../create-an-evaluation-suite/page.mdx | 319 -------- .../evaluate-tools/run-evaluations/page.mdx | 217 ------ .../why-evaluate-tools/page.mdx | 165 ----- app/en/home/google-adk/_meta.tsx | 4 +- app/en/home/google-adk/overview/page.mdx | 133 ---- .../google-adk/quickstart-python/page.mdx | 7 + .../google-adk/quickstart-typescript/page.mdx | 7 + .../home/google-adk/use-arcade-tools/page.mdx | 222 ------ app/en/home/improve-performance/_meta.tsx | 7 + .../custom-tool-improvements/page.mdx | 7 + .../eval-starter-tools/page.mdx | 7 + .../run-evaluations-2/page.mdx | 7 + .../types-of-tools/page.mdx | 7 + app/en/home/langchain/_meta.tsx | 6 +- .../langchain/auth-langchain-tools/page.mdx | 222 ------ .../home/langchain/quickstart-python/page.mdx | 7 + .../langchain/quickstart-typescript/page.mdx | 7 + .../home/langchain/use-arcade-tools/page.mdx | 243 ------ .../langchain/user-auth-interrupts/page.mdx | 373 ---------- .../langchain/using-langgraph-tools/page.mdx | 7 + app/en/home/mastra/_meta.tsx | 10 +- app/en/home/mastra/overview/page.mdx | 33 - .../mastra/quickstart-typescript/page.mdx | 7 + app/en/home/mastra/use-arcade-tools/page.mdx | 161 ---- .../home/mastra/user-auth-interrupts/page.mdx | 153 ---- app/en/home/mcp-gateways/page.mdx | 29 - app/en/home/new-functionality/_meta.tsx | 5 + .../arcade-deploy-2/page.mdx | 7 + .../new-functionality/custom-toolkit/page.mdx | 7 + .../eval-new-functionality/page.mdx | 7 + app/en/home/newest-models/_meta.tsx | 4 + .../modify-tool-new-model/page.mdx | 7 + .../newest-models/run-eval-new-model/page.mdx | 7 + app/en/home/oai-agents/_meta.tsx | 5 +- app/en/home/oai-agents/overview/page.mdx | 184 ----- .../oai-agents/quickstart-python/page.mdx | 7 + .../oai-agents/quickstart-typescript/page.mdx | 7 + .../home/oai-agents/use-arcade-tools/page.mdx | 346 --------- .../oai-agents/user-auth-interrupts/page.mdx | 442 ----------- app/en/home/observability-platforms/_meta.tsx | 4 + .../quickstarts-placeholder/page.mdx | 7 + app/en/home/open-agents/_meta.tsx | 3 + .../open-agents/quickstart-python/page.mdx | 7 + app/en/home/quickstart/page.mdx | 206 ------ app/en/home/security-section/_meta.tsx | 6 + .../security-section/enterprise-sso/page.mdx | 7 + .../identity-providers/page.mdx | 7 + .../platform-security/page.mdx | 7 + .../security-section/rbac-config/page.mdx | 7 + app/en/home/security-section/soc-2/page.mdx | 7 + app/en/home/security/page.mdx | 49 -- app/en/home/serve-tools/_meta.tsx | 4 - .../home/serve-tools/arcade-deploy/page.mdx | 165 ----- .../serve-tools/securing-arcade-mcp/page.mdx | 15 - app/en/home/third-party-apps/_meta.tsx | 7 + .../evaluation-suite/page.mdx | 7 + .../mcp-clients-section/_meta.tsx | 5 + .../claude-desktop/page.mdx | 7 + .../mcp-clients-section/cursor/page.mdx | 7 + .../visual-studio-code/page.mdx | 7 + .../mcp-gateway-auth/page.mdx | 7 + .../mcp-gateway-quickstart-2/page.mdx | 7 + app/en/home/tool-writing-basics/_meta.tsx | 9 + .../call-tools-mcp/page.mdx | 7 + .../compare-server-types/page.mdx | 7 + .../create-tool-auth/page.mdx | 7 + .../create-tool-secrets/page.mdx | 7 + .../run-evaluations/page.mdx | 7 + .../runtime-data-access/page.mdx | 7 + .../when-build-tools/page.mdx | 7 + app/en/home/tool-writing-reference/_meta.tsx | 7 + .../migrate-toolkits/page.mdx | 7 + .../organize-mcp-tools/page.mdx | 7 + .../retry-tools/page.mdx | 7 + .../useful-tool-errors/page.mdx | 7 + .../why-evaluate/page.mdx | 7 + app/en/home/triggers-section/_meta.tsx | 5 + .../background-agents/page.mdx | 7 + .../triggers-section/direct-api-call/page.mdx | 7 + .../scheduled-executions/page.mdx | 7 + app/en/home/use-tools/_meta.tsx | 8 - app/en/home/use-tools/error-handling/page.mdx | 178 ----- .../use-tools/get-tool-definitions/page.mdx | 297 -------- app/en/home/use-tools/tools-overview/page.mdx | 97 --- app/en/home/use-tools/types-of-tools/page.mdx | 63 -- app/en/home/vercelai/_meta.tsx | 2 +- .../vercelai/quickstart-typescript/page.mdx | 7 + .../home/vercelai/using-arcade-tools/page.mdx | 154 ---- app/en/home/when-build-tools/page.mdx | 34 - 137 files changed, 522 insertions(+), 10228 deletions(-) delete mode 100644 app/en/home/agentic-development/page.mdx delete mode 100644 app/en/home/arcade-cli/page.mdx delete mode 100644 app/en/home/auth/_meta.tsx delete mode 100644 app/en/home/auth/auth-tool-calling/page.mdx delete mode 100644 app/en/home/auth/call-third-party-apis-directly/page.mdx delete mode 100644 app/en/home/auth/how-arcade-helps.mdx delete mode 100644 app/en/home/auth/how-arcade-helps/page.mdx delete mode 100644 app/en/home/auth/secure-auth-production/page.mdx delete mode 100644 app/en/home/auth/tool-auth-status/page.mdx delete mode 100644 app/en/home/build-tools/_meta.tsx delete mode 100644 app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx delete mode 100644 app/en/home/build-tools/create-a-mcp-server/page.mdx delete mode 100644 app/en/home/build-tools/create-a-tool-with-auth/page.mdx delete mode 100644 app/en/home/build-tools/create-a-tool-with-secrets/page.mdx delete mode 100644 app/en/home/build-tools/migrate-from-toolkits/page.mdx delete mode 100644 app/en/home/build-tools/organize-mcp-server-tools/page.mdx delete mode 100644 app/en/home/build-tools/providing-useful-tool-errors/page.mdx delete mode 100644 app/en/home/build-tools/retry-tools-with-improved-prompt/page.mdx delete mode 100644 app/en/home/build-tools/tool-context/page.mdx delete mode 100644 app/en/home/compare-server-types/page.mdx create mode 100644 app/en/home/configure-arcade-section/_meta.tsx create mode 100644 app/en/home/configure-arcade-section/arcade-cli-section/page.mdx create mode 100644 app/en/home/configure-arcade-section/create-projects-section/page.mdx create mode 100644 app/en/home/configure-arcade-section/create-tenants-section/page.mdx create mode 100644 app/en/home/configure-arcade-section/dashboard-section/page.mdx create mode 100644 app/en/home/configure-arcade-section/overview-updated/page.mdx delete mode 100644 app/en/home/configure-arcade/page.mdx delete mode 100644 app/en/home/create-projects/page.mdx delete mode 100644 app/en/home/create-tenants/page.mdx create mode 100644 app/en/home/crewai/quickstart-python/page.mdx create mode 100644 app/en/home/crewai/quickstart-typescript/page.mdx delete mode 100644 app/en/home/crewai/use-arcade-tools/page.mdx create mode 100644 app/en/home/custom-apps/_meta.tsx create mode 100644 app/en/home/custom-apps/auth-status-check/page.mdx create mode 100644 app/en/home/custom-apps/authorized-tool-calling/page.mdx create mode 100644 app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx create mode 100644 app/en/home/custom-apps/connect-arcade-llm/page.mdx create mode 100644 app/en/home/custom-apps/test-tool-performance/page.mdx create mode 100644 app/en/home/custom-apps/tool-formats/page.mdx delete mode 100644 app/en/home/custom-mcp-server-quickstart/page.mdx delete mode 100644 app/en/home/dashboard/page.mdx delete mode 100644 app/en/home/deployment/_meta.tsx delete mode 100644 app/en/home/deployment/arcade-cloud-infra/page.mdx delete mode 100644 app/en/home/deployment/engine-configuration/page.mdx delete mode 100644 app/en/home/deployment/on-prem-mcp/page.mdx delete mode 100644 app/en/home/evaluate-tools/_meta.tsx delete mode 100644 app/en/home/evaluate-tools/create-an-evaluation-suite/page.mdx delete mode 100644 app/en/home/evaluate-tools/run-evaluations/page.mdx delete mode 100644 app/en/home/evaluate-tools/why-evaluate-tools/page.mdx delete mode 100644 app/en/home/google-adk/overview/page.mdx create mode 100644 app/en/home/google-adk/quickstart-python/page.mdx create mode 100644 app/en/home/google-adk/quickstart-typescript/page.mdx delete mode 100644 app/en/home/google-adk/use-arcade-tools/page.mdx create mode 100644 app/en/home/improve-performance/_meta.tsx create mode 100644 app/en/home/improve-performance/custom-tool-improvements/page.mdx create mode 100644 app/en/home/improve-performance/eval-starter-tools/page.mdx create mode 100644 app/en/home/improve-performance/run-evaluations-2/page.mdx create mode 100644 app/en/home/improve-performance/types-of-tools/page.mdx delete mode 100644 app/en/home/langchain/auth-langchain-tools/page.mdx create mode 100644 app/en/home/langchain/quickstart-python/page.mdx create mode 100644 app/en/home/langchain/quickstart-typescript/page.mdx delete mode 100644 app/en/home/langchain/use-arcade-tools/page.mdx delete mode 100644 app/en/home/langchain/user-auth-interrupts/page.mdx create mode 100644 app/en/home/langchain/using-langgraph-tools/page.mdx delete mode 100644 app/en/home/mastra/overview/page.mdx create mode 100644 app/en/home/mastra/quickstart-typescript/page.mdx delete mode 100644 app/en/home/mastra/use-arcade-tools/page.mdx delete mode 100644 app/en/home/mastra/user-auth-interrupts/page.mdx delete mode 100644 app/en/home/mcp-gateways/page.mdx create mode 100644 app/en/home/new-functionality/_meta.tsx create mode 100644 app/en/home/new-functionality/arcade-deploy-2/page.mdx create mode 100644 app/en/home/new-functionality/custom-toolkit/page.mdx create mode 100644 app/en/home/new-functionality/eval-new-functionality/page.mdx create mode 100644 app/en/home/newest-models/_meta.tsx create mode 100644 app/en/home/newest-models/modify-tool-new-model/page.mdx create mode 100644 app/en/home/newest-models/run-eval-new-model/page.mdx delete mode 100644 app/en/home/oai-agents/overview/page.mdx create mode 100644 app/en/home/oai-agents/quickstart-python/page.mdx create mode 100644 app/en/home/oai-agents/quickstart-typescript/page.mdx delete mode 100644 app/en/home/oai-agents/use-arcade-tools/page.mdx delete mode 100644 app/en/home/oai-agents/user-auth-interrupts/page.mdx create mode 100644 app/en/home/observability-platforms/_meta.tsx create mode 100644 app/en/home/observability-platforms/quickstarts-placeholder/page.mdx create mode 100644 app/en/home/open-agents/_meta.tsx create mode 100644 app/en/home/open-agents/quickstart-python/page.mdx delete mode 100644 app/en/home/quickstart/page.mdx create mode 100644 app/en/home/security-section/_meta.tsx create mode 100644 app/en/home/security-section/enterprise-sso/page.mdx create mode 100644 app/en/home/security-section/identity-providers/page.mdx create mode 100644 app/en/home/security-section/platform-security/page.mdx create mode 100644 app/en/home/security-section/rbac-config/page.mdx create mode 100644 app/en/home/security-section/soc-2/page.mdx delete mode 100644 app/en/home/security/page.mdx delete mode 100644 app/en/home/serve-tools/_meta.tsx delete mode 100644 app/en/home/serve-tools/arcade-deploy/page.mdx delete mode 100644 app/en/home/serve-tools/securing-arcade-mcp/page.mdx create mode 100644 app/en/home/third-party-apps/_meta.tsx create mode 100644 app/en/home/third-party-apps/evaluation-suite/page.mdx create mode 100644 app/en/home/third-party-apps/mcp-clients-section/_meta.tsx create mode 100644 app/en/home/third-party-apps/mcp-clients-section/claude-desktop/page.mdx create mode 100644 app/en/home/third-party-apps/mcp-clients-section/cursor/page.mdx create mode 100644 app/en/home/third-party-apps/mcp-clients-section/visual-studio-code/page.mdx create mode 100644 app/en/home/third-party-apps/mcp-gateway-auth/page.mdx create mode 100644 app/en/home/third-party-apps/mcp-gateway-quickstart-2/page.mdx create mode 100644 app/en/home/tool-writing-basics/_meta.tsx create mode 100644 app/en/home/tool-writing-basics/call-tools-mcp/page.mdx create mode 100644 app/en/home/tool-writing-basics/compare-server-types/page.mdx create mode 100644 app/en/home/tool-writing-basics/create-tool-auth/page.mdx create mode 100644 app/en/home/tool-writing-basics/create-tool-secrets/page.mdx create mode 100644 app/en/home/tool-writing-basics/run-evaluations/page.mdx create mode 100644 app/en/home/tool-writing-basics/runtime-data-access/page.mdx create mode 100644 app/en/home/tool-writing-basics/when-build-tools/page.mdx create mode 100644 app/en/home/tool-writing-reference/_meta.tsx create mode 100644 app/en/home/tool-writing-reference/migrate-toolkits/page.mdx create mode 100644 app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx create mode 100644 app/en/home/tool-writing-reference/retry-tools/page.mdx create mode 100644 app/en/home/tool-writing-reference/useful-tool-errors/page.mdx create mode 100644 app/en/home/tool-writing-reference/why-evaluate/page.mdx create mode 100644 app/en/home/triggers-section/_meta.tsx create mode 100644 app/en/home/triggers-section/background-agents/page.mdx create mode 100644 app/en/home/triggers-section/direct-api-call/page.mdx create mode 100644 app/en/home/triggers-section/scheduled-executions/page.mdx delete mode 100644 app/en/home/use-tools/_meta.tsx delete mode 100644 app/en/home/use-tools/error-handling/page.mdx delete mode 100644 app/en/home/use-tools/get-tool-definitions/page.mdx delete mode 100644 app/en/home/use-tools/tools-overview/page.mdx delete mode 100644 app/en/home/use-tools/types-of-tools/page.mdx create mode 100644 app/en/home/vercelai/quickstart-typescript/page.mdx delete mode 100644 app/en/home/vercelai/using-arcade-tools/page.mdx delete mode 100644 app/en/home/when-build-tools/page.mdx diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index a2dbc4b7f..04ac8743a 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -1,4 +1,4 @@ -import { BadgeHelp, Globe, HeartPulse, Home, Shield } from "lucide-react"; +import { BadgeHelp, Globe, HeartPulse, Home } from "lucide-react"; import type { MetaRecord } from "nextra"; function TitleWithIcon({ @@ -58,49 +58,8 @@ export const meta: MetaRecord = { title: "Sample agents with tool calling", href: "/sample-agents", }, - "configure-arcade": { + "configure-arcade-section": { title: "Configure Arcade", - href: "/configure-arcade", - }, - "overview-updated": { - title: "Overview", - href: "/overview-updated", - }, - dashboard: { - title: "Dashboard", - href: "/dashboard", - }, - "create-tenants": { - title: "Create Tenants", - href: "/create-tenants", - }, - "create-projects": { - title: "Create Projects", - href: "/create-projects", - }, - "arcade-cli": { - title: "Using Arcade's CLI", - href: "/arcade-cli", - }, - "security-compliance": { - title: "Security & Compliance", - href: "/security-compliance", - }, - "identity-providers": { - title: "Supported Identity Providers", - href: "/identity-providers", - }, - "soc-2": { - title: "SOC-2", - href: "/soc-2", - }, - "enterprise-sso": { - title: "Enterprise Single Sign On", - href: "/enterprise-sso", - }, - "rbac-config": { - title: "Configuring Role Based Access Control for your organization", - href: "/rbac-config", }, "-- Tool Calling": { type: "separator", @@ -115,192 +74,33 @@ export const meta: MetaRecord = { href: "/error-handling", }, "third-party-apps": { - type: "separator", title: "In 3rd party applications", }, - "mcp-gateway-quickstart-2": { - title: "Calling tools in 3rd party agents, apps, or IDEs", - href: "/mcp-gateway-quickstart", - }, - "mcp-clients": { - title: "Connecting to a MCP Client", - }, - "cursor-client": { - title: "Cursor", - href: "/cursor-client", - }, - "claude-desktop": { - title: "Claude Desktop", - href: "/claude-desktop", - }, - "vscode-client": { - title: "Visual Studio Code", - href: "/vscode-client", - }, - "evaluation-suite": { - title: "Creating an evaluation suite to test tools", - href: "/evaluation-suite", - }, "custom-apps": { - type: "separator", title: "In custom applications", }, - "calling-tools-custom-apps-2": { - title: "Calling tools in your custom apps", - href: "/calling-tools-custom-apps", - }, - "authorized-tool-calling": { - title: "Authorized Tool Calling", - href: "/authorized-tool-calling", - }, - "auth-status-check": { - title: "Checking Authorization Status", - href: "/auth-status-check", - }, - "tool-formats": { - title: "Tool formats", - href: "/tool-formats", - }, - "connect-arcade-llm": { - title: "Connecting Arcade tools to your LLM", - href: "/connect-arcade-llm", - }, - "test-tool-performance": { - title: "Testing tool performance", - href: "/test-tool-performance", - }, - triggers: { - type: "separator", + "triggers-section": { title: "Triggers", }, - "background-agents": { - title: "Set up a background agent using events", - href: "/background-agents", - }, - "scheduled-executions": { - title: "Set up scheduled tool executions", - href: "/scheduled-executions", - }, - "direct-api-call": { - title: "Direct Third-Party API Call", - href: "/direct-api-call", - }, "-- Tool Writing": { type: "separator", title: "Tool Writing", }, - "learn-basics": { - type: "separator", + "tool-writing-basics": { title: "Learn the basics", }, - "when-build-tools": { - title: "When to build tools", - href: "/when-build-tools", - }, - "compare-server-types": { - title: "Compare Server Types", - }, - "build-tools": { - title: "Build MCP Server to write custom tools", - }, - "create-tool-auth": { - title: "Create a tool with auth", - href: "/create-tool-auth", - }, - "create-tool-secrets": { - title: "Create a tool with secrets", - href: "/create-tool-secrets", - }, - "runtime-data-access": { - title: "Accessing runtime data", - href: "/runtime-data-access", - }, - "call-tools-mcp": { - title: "Call tools from MCP clients", - href: "/call-tools-mcp", - }, - "evaluate-tools": { - title: "Create an evaluation suite", - }, - "run-evaluations": { - title: "Run evaluations", - href: "/run-evaluations", - }, "improve-performance": { - type: "separator", title: "Building tools to get more performance out of existing toolkits", }, - "types-of-tools": { - title: "Types of tools", - href: "/types-of-tools", - }, - "eval-starter-tools": { - title: "Write eval to assess combo of starter tools", - href: "/eval-starter-tools", - }, - "custom-tool-improvements": { - title: "Write custom tool that improves on relevant Starter tools", - href: "/custom-tool-improvements", - }, - "run-evaluations-2": { - title: "Run evaluations", - href: "/run-evaluations", - }, - "serve-tools": { - title: "Arcade Deploy", - }, "new-functionality": { - type: "separator", title: "Building tools with agent functionality that doesn't exist", }, - "eval-new-functionality": { - title: "Write eval for functionality you want", - href: "/eval-new-functionality", - }, - "custom-toolkit": { - title: "Write custom toolkit", - href: "/custom-toolkit", - }, - "arcade-deploy-2": { - title: "Arcade Deploy", - href: "/arcade-deploy", - }, "newest-models": { - type: "separator", title: "Ensure tools work with the newest models", }, - "run-eval-new-model": { - title: "Run existing eval and observe outcome with new model", - href: "/run-eval-new-model", - }, - "modify-tool-new-model": { - title: "Modify tool to work well with new model", - href: "/modify-tool-new-model", - }, "tool-writing-reference": { - type: "separator", title: "Reference", }, - "organize-mcp-tools": { - title: "Organize MCP server tools", - href: "/organize-mcp-tools", - }, - "useful-tool-errors": { - title: "Providing useful tool errors", - href: "/useful-tool-errors", - }, - "retry-tools": { - title: "Retry tools with improved prompt", - href: "/retry-tools", - }, - "migrate-toolkits": { - title: "Migrate from toolkits to MCP Servers", - href: "/migrate-toolkits", - }, - "why-evaluate": { - title: "Why evaluate tools?", - href: "/why-evaluate", - }, "-- Configuring Arcade with Agent Orchestrators": { type: "separator", title: "Configuring Arcade with Agent Orchestrators", @@ -321,76 +121,30 @@ export const meta: MetaRecord = { langchain: { title: "LangGraph", }, - "langgraph-python": { - title: "Quickstart (Python)", - href: "/langgraph-python", - }, - "langgraph-typescript": { - title: "Quickstart (Typescript)", - href: "/langgraph-typescript", - }, - "langgraph-tools": { - title: "Using LangGraph tools", - href: "/langgraph-tools", - }, "oai-agents": { title: "OpenAI Agents", }, - "openai-python": { - title: "Quickstart (Python)", - href: "/openai-python", - }, - "openai-typescript": { - title: "Quickstart (Typescript)", - href: "/openai-typescript", - }, crewai: { title: "CrewAI", }, - "crewai-python": { - title: "Quickstart (Python)", - href: "/crewai-python", - }, - "crewai-typescript": { - title: "Quickstart (Typescript)", - href: "/crewai-typescript", - }, - "crewai-custom-auth": { - title: "Custom auth flow", - href: "/crewai-custom-auth", - }, "open-agents": { title: "OpenAgents", - href: "/open-agents", - }, - "openagents-python": { - title: "Quickstart (Python)", - href: "/openagents-python", }, "google-adk": { title: "Google ADK", }, - "google-adk-python": { - title: "Quickstart (Python)", - href: "/google-adk-python", - }, - "google-adk-typescript": { - title: "Quickstart (Typescript)", - href: "/google-adk-typescript", - }, mastra: { title: "Mastra", }, - "mastra-typescript": { - title: "Quickstart (Typescript)", - href: "/mastra-typescript", - }, vercelai: { title: "Vercel AI", }, - "vercelai-typescript": { - title: "Quickstart (Typescript)", - href: "/vercelai-typescript", + "-- Configuring Arcade with Observability Platforms": { + type: "separator", + title: "Configuring Arcade with Observability Platforms", + }, + "observability-platforms": { + title: "Observability Platforms", }, "-- Scaling your app to many end-users": { type: "separator", @@ -403,14 +157,6 @@ export const meta: MetaRecord = { "auth-providers": { title: "Customizing Auth", }, - "auth-overview": { - title: "Overview", - href: "/auth-overview", - }, - oauth2: { - title: "OAuth 2.0", - href: "/oauth2", - }, "-- Hosting Options": { type: "separator", title: "Hosting Options", @@ -431,6 +177,13 @@ export const meta: MetaRecord = { title: "Engine configuration", href: "/engine-config", }, + "-- Security": { + type: "separator", + title: "Security", + }, + "security-section": { + title: "Security & Compliance", + }, "-- Guides": { type: "separator", title: "Guides", @@ -462,9 +215,6 @@ export const meta: MetaRecord = { "contact-us": { title: Contact us, }, - security: { - title: Security, - }, status: { title: Status, href: "https://status.arcade.dev/", diff --git a/app/en/home/agentic-development/page.mdx b/app/en/home/agentic-development/page.mdx deleted file mode 100644 index 40845e0e1..000000000 --- a/app/en/home/agentic-development/page.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Agentic Development" -description: "Learn how to speed up your development with agents in your IDEs" ---- - -# Agentic Development - -Give your AI IDE access to Arcade.dev's documentation using our [llms.txt](/llms.txt) file, or use [context7](https://context7.com/arcadeai/docs). This allows Claude Code, Cursor, and other AI IDEs to access the documentation and help you write code. - -## LLMs.txt - -LLMs.txt is a file format that allows you to give your AI IDE access to Arcade.dev's documentation in a format that can be easily parsed by the LLM. All you need to do is paste in the content of the file into your IDE's settings, or reference the docs, e.g. via [Cursor's `@docs` annotation](https://cursor.com/docs/context/symbols#docs). - -Our LLMs.txt files are available at [`/llms.txt`](/llms.txt). - -![LLMs.txt example](/images/agentic-development/cursor-llms-txt.png) - -Learn more about the LLMs.txt file format [here](https://llmstxt.org/). - -## Context7 - -Context7 is an MCP server designed to provide Large Language Models (LLMs) and AI code editors with up-to-date, version-specific documentation and code examples. It helps prevent AI models from "hallucinating" or providing outdated code by fetching accurate information directly from its knowledge base and injecting it into the LLM's prompt, ensuring more reliable and accurate coding assistance - -To use Context7, you first need to add the [Context7 MCP server](https://github.com/upstash/context7) to your editor, and then select the [`arcadeai/docs` project](https://context7.com/arcadeai/docs). - -Learn more about Context7 [here](https://context7.com/). diff --git a/app/en/home/arcade-cli/page.mdx b/app/en/home/arcade-cli/page.mdx deleted file mode 100644 index 094c3bebf..000000000 --- a/app/en/home/arcade-cli/page.mdx +++ /dev/null @@ -1,413 +0,0 @@ ---- -title: "Arcade CLI" -description: "Learn how to install and use the Arcade CLI" ---- - -import { Tabs, Callout } from "nextra/components"; - -# The Arcade CLI - -The Arcade CLI is a command-line tool that allows you to manage your Arcade deployments, generate, test, and manage your MCP servers, and more. - -## Install the Arcade CLI - -In your terminal, run the following command to install the `arcade-mcp` package - Arcade's CLI: - - - - - ```bash - uv tool install arcade-mcp - ``` - - - This will install the Arcade CLI as a [uv tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it available system wide. - - - - - - - ```bash - pip install arcade-mcp - ``` - - - - -## Usage - -```bash - Usage: arcade [OPTIONS] COMMAND [ARGS]... - - Arcade CLI - Build, deploy, and manage MCP servers and AI tools. Create - new projects, run servers with multiple transports, configure clients, and - deploy to Arcade Cloud. - -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --version -v Print version and exit. │ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ User ───────────────────────────────────────────────────────────────────╮ -│ login Log in to Arcade Cloud │ -│ logout Log out of Arcade Cloud │ -│ dashboard Open the Arcade Dashboard in a web browser │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ Build ──────────────────────────────────────────────────────────────────╮ -│ new Create a new server package directory. Example usage: arcade new │ -│ my_mcp_server │ -│ show Show the installed tools or details of a specific tool │ -│ evals Run tool calling evaluations │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ Run ────────────────────────────────────────────────────────────────────╮ -│ mcp Run MCP servers with different transports │ -│ deploy Deploy MCP servers to Arcade │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ Manage ─────────────────────────────────────────────────────────────────╮ -│ configure Configure MCP clients to connect to your server │ -│ server Manage deployments of tool servers (logs, list, etc) │ -│ secret Manage tool secrets in the cloud (set, unset, list) │ -╰──────────────────────────────────────────────────────────────────────────╯ - - Pro tip: use --help after any command to see command-specific options. -``` - -You can learn more about any of the commands by running `arcade --help`, e.g. `arcade new --help`. - -## `arcade login` - -```bash - Usage: arcade login [OPTIONS] - - Log in to Arcade Cloud - -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --host -h TEXT The Arcade Cloud host to log in to. │ -│ [default: cloud.arcade.dev] │ -│ --port -p INTEGER The port of the Arcade Cloud host (if │ -│ running locally). │ -│ [default: None] │ -│ --callback-host TEXT The host to use to complete the auth │ -│ flow - this should be the same as the │ -│ host that the CLI is running on. │ -│ Include the port if needed. │ -│ [default: None] │ -│ --debug -d Show debug information │ -│ --help Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade logout` - -```bash - Usage: arcade logout [OPTIONS] - - Log out of Arcade Cloud - -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --debug -d Show debug information │ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade dashboard` - -```bash - - Usage: arcade dashboard [OPTIONS] - - Open the Arcade Dashboard in a web browser - -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --host -h TEXT The Arcade Engine host that serves the │ -│ dashboard. │ -│ [default: api.arcade.dev] │ -│ --port -p INTEGER The port of the Arcade Engine. │ -│ [default: None] │ -│ --local -l Open the local dashboard instead of the │ -│ default remote dashboard. │ -│ --tls Whether to force TLS for the connection to │ -│ the Arcade Engine. │ -│ --no-tls Whether to disable TLS for the connection to │ -│ the Arcade Engine. │ -│ --debug -d Show debug information │ -│ --help Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade new` - -```bash - Usage: arcade new [OPTIONS] SERVER_NAME - - Create a new server package directory. Example usage: arcade new - my_mcp_server - -╭─ Arguments ──────────────────────────────────────────────────────────────╮ -│ * server_name TEXT The name of the server to create │ -│ [default: None] │ -│ [required] │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --dir TEXT tools directory path │ -│ [default: current directory] │ -│ --debug -d Show debug information │ -│ --full -f Create a starter MCP server (pyproject.toml, │ -│ server.py, .env.example) │ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade show` - -```bash - Usage: arcade show [OPTIONS] - - Show the installed tools or details of a specific tool - -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --server -T TEXT The server to show the tools of │ -│ [default: None] │ -│ --tool -t TEXT The specific tool to show details for │ -│ [default: None] │ -│ --host -h TEXT The Arcade Engine address to show the │ -│ tools/servers of. │ -│ [default: api.arcade.dev] │ -│ --local -l Show the local environment's catalog instead │ -│ of an Arcade Engine's catalog. │ -│ --port -p INTEGER The port of the Arcade Engine. │ -│ [default: None] │ -│ --tls Whether to force TLS for the connection to │ -│ the Arcade Engine. If not specified, the │ -│ connection will use TLS if the engine URL │ -│ uses a 'https' scheme. │ -│ --no-tls Whether to disable TLS for the connection to │ -│ the Arcade Engine. │ -│ --full -f Show full server response structure including │ -│ error, logs, and authorization fields (only │ -│ applies when used with -t/--tool). │ -│ --debug -d Show debug information │ -│ --help Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade evals` - -```bash - Usage: arcade evals [OPTIONS] [DIRECTORY] - - Run tool calling evaluations - -╭─ Arguments ──────────────────────────────────────────────────────────────╮ -│ directory [DIRECTORY] Directory containing evaluation files │ -│ [default: .] │ -╰──────────────────────────────────────────────────────────────────────────╯ -╭─ Options ────────────────────────────────────────────────────────────────╮ -│ --details -d Show detailed results │ -│ --max-concurrent -c INTEGER Maximum number of concurrent │ -│ evaluations (default: 1) │ -│ [default: 1] │ -│ --models -m TEXT The models to use for evaluation │ -│ (default: gpt-4o). Use commas to │ -│ separate multiple models. All │ -│ models must belong to the same │ -│ provider. │ -│ [default: gpt-4o] │ -│ --provider -p [openai] The provider of the models to use │ -│ for evaluation. │ -│ [default: openai] │ -│ --provider-api-key -k TEXT The model provider API key. If not │ -│ provided, will look for the │ -│ appropriate environment variable │ -│ based on the provider (e.g., │ -│ OPENAI_API_KEY for openai │ -│ provider), first in the current │ -│ environment, then in the current │ -│ working directory's .env file. │ -│ [default: None] │ -│ --debug Show debug information │ -│ --help -h Show this message and exit. │ -╰──────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade mcp` - -```bash -Usage: arcade mcp [OPTIONS] [TRANSPORT] - - Run MCP servers with different transports - -╭─ Arguments ────────────────────────────────────────────────────────────────────────╮ -│ transport [TRANSPORT] Transport type: stdio, http │ -│ [default: http] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────╮ -│ --host TEXT Host to bind to (HTTP mode only) │ -│ [default: 127.0.0.1] │ -│ --port INTEGER Port to bind to (HTTP mode only) │ -│ [default: 8000] │ -│ --tool-package,--package -p TEXT Specific tool package to load (e.g., │ -│ 'github' for arcade-github) │ -│ [default: None] │ -│ --discover-installed,--all Discover all installed arcade tool │ -│ packages │ -│ --show-packages Show loaded packages during discovery │ -│ --reload Enable auto-reload on code changes │ -│ (HTTP mode only) │ -│ --debug Enable debug mode with verbose │ -│ logging │ -│ --otel-enable Send logs to OpenTelemetry │ -│ --env-file TEXT Path to environment file │ -│ [default: None] │ -│ --name TEXT Server name │ -│ [default: None] │ -│ --version TEXT Server version │ -│ [default: None] │ -│ --cwd TEXT Working directory to run from │ -│ [default: None] │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade deploy` - -```bash - Usage: arcade deploy [OPTIONS] - - Deploy MCP servers to Arcade - -╭─ Options ──────────────────────────────────────────────────────────────────────────╮ -│ --entrypoint -e TEXT Relative path to the Python file that runs the MCPApp │ -│ instance (relative to project root). This file must │ -│ execute the run() method on your MCPApp instance when │ -│ invoked directly. │ -│ [default: server.py] │ -│ --debug -d Show debug information │ -│ --help Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Advanced ─────────────────────────────────────────────────────────────────────────╮ -│ --skip-validate,--yolo Skip running the server locally │ -│ for health/metadata checks. When │ -│ set, you must provide │ -│ --server-name and │ -│ --server-version. Secret handling │ -│ is controlled by --secrets. │ -│ --server-name -n TEXT Explicit server name to use when │ -│ --skip-validate is set. Only used │ -│ when --skip-validate is set. │ -│ [default: None] │ -│ --server-version -v TEXT Explicit server version to use │ -│ when --skip-validate is set. Only │ -│ used when --skip-validate is set. │ -│ [default: None] │ -│ --secrets -s [auto|all|skip] How to upsert secrets before │ -│ deploy: auto (default): During │ -│ validation, discover required │ -│ secret KEYS and upsert only │ -│ those. If --skip-validate is set, │ -│ auto becomes skip. all: Upsert │ -│ every key/value pair from your │ -│ server's .env file regardless of │ -│ what the server needs. skip: Do │ -│ not upsert any secrets (assumes │ -│ they are already present in │ -│ Arcade). │ -│ [default: auto] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade configure` - -```bash - Usage: arcade configure [OPTIONS] CLIENT:{claude|cursor|vscode} - - Configure MCP clients to connect to your server - -╭─ Arguments ────────────────────────────────────────────────────────────────────────╮ -│ * client CLIENT:{claude|cursor|vscode} The MCP client to configure │ -│ (claude, cursor, vscode) │ -│ [default: None] │ -│ [required] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────╮ -│ --transport -t [stdio|http] The transport to use for the MCP server │ -│ configuration │ -│ [default: stdio] │ -│ --debug -d Show debug information │ -│ --help Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Stdio Options ────────────────────────────────────────────────────────────────────╮ -│ --entrypoint -e TEXT The name of the Python file in the current directory │ -│ that runs the server. This file must run the server │ -│ when invoked directly. Only used for stdio servers. │ -│ [default: server.py] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Configuration File Options ───────────────────────────────────────────────────────╮ -│ --name -n TEXT Optional name of the server to set in the configuration │ -│ file (defaults to the name of the current directory) │ -│ [default: None] │ -│ --config -c PATH Optional path to a specific MCP client config file │ -│ (overrides default path) │ -│ [default: None] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ HTTP Options ─────────────────────────────────────────────────────────────────────╮ -│ --host -h [local|arcade] The host of the HTTP server to configure. Use │ -│ 'local' to connect to a local MCP server or │ -│ 'arcade' to connect to an Arcade Cloud MCP server. │ -│ [default: local] │ -│ --port -p INTEGER Port for local HTTP servers │ -│ [default: 8000] │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade server` - -```bash -Usage: arcade server [OPTIONS] COMMAND [ARGS]... - - Manage deployments of tool servers (logs, list, etc) - -╭─ Options ──────────────────────────────────────────────────────────────────────────╮ -│ --host -h TEXT The Arcade Engine host. │ -│ [default: api.arcade.dev] │ -│ --port -p INTEGER The port of the Arcade Engine host. │ -│ [default: None] │ -│ --tls Whether to force TLS for the connection to the Arcade │ -│ Engine. │ -│ --no-tls Whether to disable TLS for the connection to the Arcade │ -│ Engine. │ -│ --help Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Commands ─────────────────────────────────────────────────────────────────────────╮ -│ list List all workers │ -│ enable Enable a worker │ -│ disable Disable a worker │ -│ rm Remove a worker │ -│ logs Get logs for a worker │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` - -## `arcade secret` - -```bash -Usage: arcade secret [OPTIONS] COMMAND [ARGS]... - - Manage tool secrets in the cloud (set, unset, list) - -╭─ Options ──────────────────────────────────────────────────────────────────────────╮ -│ --host -h TEXT The Arcade Engine host. │ -│ [default: api.arcade.dev] │ -│ --port -p INTEGER The port of the Arcade Engine host. │ -│ [default: None] │ -│ --tls Whether to force TLS for the connection to the Arcade │ -│ Engine. │ -│ --no-tls Whether to disable TLS for the connection to the Arcade │ -│ Engine. │ -│ --help Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Commands ─────────────────────────────────────────────────────────────────────────╮ -│ set Set tool secret(s) using KEY=VALUE pairs or from .env file │ -│ list List all tool secrets in Arcade Cloud │ -│ unset Delete tool secret(s) by key names │ -╰────────────────────────────────────────────────────────────────────────────────────╯ -``` diff --git a/app/en/home/auth/_meta.tsx b/app/en/home/auth/_meta.tsx deleted file mode 100644 index 025a383e3..000000000 --- a/app/en/home/auth/_meta.tsx +++ /dev/null @@ -1,7 +0,0 @@ -export default { - "how-arcade-helps": "How Arcade Helps", - "auth-tool-calling": "Authorized Tool Calling", - "tool-auth-status": "Checking Authorization Status", - "call-third-party-apis-directly": "Direct Third-Party API Call", - "secure-auth-production": "Secure Auth in Production", -}; diff --git a/app/en/home/auth/auth-tool-calling/page.mdx b/app/en/home/auth/auth-tool-calling/page.mdx deleted file mode 100644 index 2143e4714..000000000 --- a/app/en/home/auth/auth-tool-calling/page.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Authorized Tool Calling" -description: "Guide on calling tools that require authorization" ---- - -# Authorized Tool Calling - -Arcade provides an authorization system that handles OAuth 2.0, API keys, and user tokens needed by AI agents to access external services through tools. This means your AI agents can now act on behalf of users securely and privately. - -With Arcade, developers can now create agents that can as _as the end user of their application_ to perform tasks like: - -- Creating a new Zoom meeting -- Sending or reading email -- Answering questions about files in Google Drive. - -Arcade also allows for actions (tools) to be authorized directly. For example, to access a user's Gmail account, you can utilize the following guide. - -import { Steps, Tabs, Callout } from "nextra/components"; - - - -### Initialize the client - -Import the Arcade client in a Python/Javascript script. The client automatically finds API keys set by `arcade login`. - - - -```python -from arcadepy import Arcade - -client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable - -```` - - -```js -import Arcade from "@arcadeai/arcadejs"; - -const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable -```` - - - - -### Authorize a tool directly - -Many tools require authorization. For example, the `Gmail.ListEmails` tool requires authorization with Google. - -This authorization must be approved by the user. By approving, the user allows your agent or app to access only the data they've approved. - - - - -```python -# As the developer, you must identify the user you're authorizing -# and pass a unique identifier for them (e.g. an email or user ID) to Arcade: -USER_ID = "{arcade_user_id}" - -# Request access to the user's Gmail account -auth_response = client.tools.authorize( - tool_name="Gmail.ListEmails", - user_id=USER_ID, -) - -if auth_response.status != "completed": - print(f"Click this link to authorize: {auth_response.url}") -``` - - - -```js -// As the developer, you must identify the user you're authorizing -// and pass a unique identifier for them (e.g. an email or user ID) to Arcade: -const userId = "{arcade_user_id}"; - -// Request access to the user's Gmail account -const authResponse = await client.tools.authorize({ -tool_name: "Gmail.ListEmails", -user_id: userId, -}); - -if (authResponse.status !== "completed") { -console.log(`Click this link to authorize: ${authResponse.url}`); -} - -```` - - - - -This will print a URL that the user must visit to approve the authorization. - -### Check for authorization status - -You can wait for the authorization to complete using the following methods: - - - - ```python - client.auth.wait_for_completion(auth_response) - ``` - - - - ```js - await client.auth.waitForCompletion(authResponse); - ``` - - - - -### Call the tool with authorization - -Once the user has approved the action, you can run the tool. You only need to pass the `user_id`: - - - - - -```python -emails_response = client.tools.execute( - tool_name="Gmail.ListEmails", - user_id=USER_ID, -) -print(emails_response) -```` - - - - -```js -const emailsResponse = await client.tools.execute({ - tool_name: "Gmail.ListEmails", - user_id: userId, -}); - -console.log(emailsResponse.output.value); -``` - - - - -Arcade remembers the user's authorization tokens, so you don't have to! Next time the user runs the same tool, they won't have to go through the authorization process again until the auth expires or is revoked. - -### How it works - -When you call a tool with `client.tools.execute()`, Arcade: - -1. Checks for authorization. -2. Routes the request to the tool's provider. -3. Returns the tool's response. - -With `client.tools.authorize()`, you can also authorize tools for later use. - -These APIs give you programmatic control over tool calling. - - - -### Next steps - -Arcade also allows you to [build your own tools](/home/build-tools/create-a-mcp-server) to integrate any custom functionality or API to your Agent or AI workflows. - -Your tools can use the [service providers supported by Arcade](/home/auth-providers) or you can integrate with any [OAuth2-compatible service](/home/auth-providers/oauth2). diff --git a/app/en/home/auth/call-third-party-apis-directly/page.mdx b/app/en/home/auth/call-third-party-apis-directly/page.mdx deleted file mode 100644 index fbc3d8c23..000000000 --- a/app/en/home/auth/call-third-party-apis-directly/page.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: "Direct Third-Party API Call" -description: "Guide on how to retrieve an authorization token to call third-party APIs directly" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; -import { SignupLink } from "@/app/_components/analytics"; - -# Direct Third-Party API Call - -In this guide, you'll learn how to use Arcade to obtain user authorization and interact with third-party services by calling their API endpoints directly, without using Arcade for tool execution or definition. We'll use Google's Gmail API as an example to demonstrate how to: - -- Get authorization tokens through Arcade -- Handle user authentication flows -- Use tokens with external services - -This can be useful when you need to manage authorization flows in your application. - - - -### Prerequisites - -- Sign up for an Arcade account if you haven't already -- Generate an [Arcade API key](/home/api-keys) and take note of it - -### Install required libraries - - - ```bash pip install arcadepy google-api-python-client google-auth-httplib2 google-auth-oauthlib ``` - ```bash npm install @arcadeai/arcadejs googleapis ``` - - -### Start coding - - - -Create a new file `direct_api_call.py` and import all libraries we're going to use: - -```python -from arcadepy import Arcade -from google.oauth2.credentials import Credentials -from googleapiclient.discovery import build -``` - - - -Create a new file `direct_api_call.js` and import all libraries we're going to use: - -```javascript -import { Arcade } from "@arcadeai/arcadejs"; -import { google } from "googleapis"; -``` - - - - -### Initialize the Arcade client - -Create an instance of the Arcade client: - - - -```python -client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable -``` - - -```javascript -const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable -``` - - - - -### Initiate an authorization request - -Use `client.auth.start()` to initiate the authorization process: - - - -```python -# This would be your app's internal ID for the user (an email, UUID, etc.) -user_id = "{arcade_user_id}" - -# Start the authorization process - -auth_response = client.auth.start( -user_id=user_id, -provider="google", -scopes=["https://www.googleapis.com/auth/gmail.readonly"], -) - -```` - - -```javascript -// Your app's internal ID for the user (an email, UUID, etc). -// It's used internally to identify your user in Arcade, not to identify with the Gmail service. -// Use your Arcade account email for testing: -const user_id = "{arcade_user_id}"; - -// Start the authorization process -let auth_response = await client.auth.start(user_id, "google", { - scopes: ["https://www.googleapis.com/auth/gmail.readonly"], -}); -```` - - - - -### Guide the user through authorization - -If authorization is not completed, prompt the user to visit the authorization URL: - - - -```python -if auth_response.status != "completed": - print("Please complete the authorization challenge in your browser:") - print(auth_response.url) -``` - - -```javascript -if (auth_response.status !== "completed") { - console.log("Please complete the authorization challenge in your browser:"); - console.log(auth_response.url); -} -``` - - - - -### Wait for the user to authorize the request - - - -```python -# Wait for the authorization to complete -auth_response = client.auth.wait_for_completion(auth_response) -``` - - -```javascript -// Wait for the authorization to complete -auth_response = await client.auth.waitForCompletion(auth_response); -``` - - - - -### Use the obtained token - -Once authorization is complete, you can use the obtained token to access the third-party service: - - - -```python -credentials = Credentials(auth_response.context.token) -gmail = build("gmail", "v1", credentials=credentials) - -email_messages = ( -gmail.users().messages().list(userId="me").execute().get("messages", []) -) - -print(email_messages) - -```` - - -```javascript -const auth = new google.auth.OAuth2(); -auth.setCredentials({ access_token: auth_response.context.token }); -const gmail = google.gmail({ version: "v1", auth }); - -// List email messages -const response = await gmail.users.messages.list({ - userId: "me", -}); - -const email_messages = response.data.messages || []; -console.log(email_messages); -```` - - - - -### Execute the code - - - ```python python3 direct_api_call.py ``` - ```javascript node direct_api_call.js ``` - - -You should see an output similar to this:, which is a list of the email messages returned by the Gmail API: - -```text -[{'id': '195f77a8ce90f2c1', 'threadId': '195f77a8ce90f2c1'}, {'id': '195ed467a90e8538', 'threadId': '195ed467a90e8538'}, ...] -``` - -For each item in the list/array, you could use the [`users.messages.get`](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get) endpoint to get the full message details. - - - -Consider using the [Arcade Gmail MCP Server](/mcp-servers/productivity/gmail), which simplifies the process for retrieving email messages even further! The pattern described here is useful if you need to directly get a token to use with Google in other parts of your codebase. - -### How it works - -By using `client.auth.start` and `client.auth.wait_for_completion`, you leverage Arcade to manage the OAuth flow for user authorization. - -Arcade handles the authorization challenges and tokens, simplifying the process for you. - -### Next steps - -Integrate this authorization flow into your application, and explore how you can manage different [auth providers](/home/auth-providers) and scopes. diff --git a/app/en/home/auth/how-arcade-helps.mdx b/app/en/home/auth/how-arcade-helps.mdx deleted file mode 100644 index 12ea2984f..000000000 --- a/app/en/home/auth/how-arcade-helps.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "How Arcade helps" -description: "Learn how Arcade helps with auth and tool calling" ---- - -import { Tabs } from "nextra/components"; - -# How Arcade helps with Agent Authorization - -### The challenges that Arcade solves - -Applications that use models to perform tasks (_agentic applications_) commonly require access to sensitive data and services. Authentication complexities often hinder AI from performing tasks that require user-specific information, like what emails you recently received or what's coming up on your calendar. - -To retrieve this information, agentic applications need to be able to authenticate and authorize access to external services you use like Gmail or Google Calendar. - -Authenticating to retrieve information, however, is not the only challenge. Agentic applications also need to authenticate in order to **act** on your behalf - like sending an email or updating your calendar. - -Without auth, AI agents are severely limited in what they can do. - -### How Arcade solves this - -Arcade provides an authorization system that handles OAuth 2.0, API keys, and user tokens needed by AI agents to access external services through tools. This means your AI agents can now act on behalf of users securely and privately. - -With Arcade, developers can now create agents that can _act as the end users of their application_ to perform tasks like: - -- Creating a new Zoom meeting -- Sending or reading email -- Answering questions about files in Google Drive. - -### Auth permissions and scopes - -Each tool in Arcade's MCP Servers has a set of required permissions - or, more commonly referred to in OAuth2, **scopes**. For example, the [`Gmail.SendEmail`](/mcp-servers/productivity/gmail#gmailsendemail) tool requires the [`https://www.googleapis.com/auth/gmail.send`](https://developers.google.com/identity/protocols/oauth2/scopes#gmail) scope. - -A scope is what the user has authorized someone else (in this case, the AI agent) to do on their behalf. In any OAuth2-compatible service, each kind of action requires a different set of permissions. This gives the user fine-grained control over what data third-party services can access and what actions can be executed in their accounts. - -When a tool is called, the Arcade Engine will check if the user has granted the required permissions. If not, it will automatically prompt the user to authorize the tool, coordinating the OAuth2 flow with the service provider. - -### How to implement OAuth2-authorized tool calling - -To learn how Arcade allows for actions (tools) to be authorized through OAuth2 and how to implement it, check out [Authorized Tool Calling](/home/auth/auth-tool-calling). - -### Tools that don't require authorization - -Some tools, like [`GoogleSearch.Search`](/mcp-servers/search/google_search#googlesearchsearch), allow AI agents to retrieve information or perform actions without needing user-specific authorization. - - - -```python -from arcadepy import Arcade - -client = Arcade(api_key="arcade_api_key") # or set the ARCADE_API_KEY env var - -# Use the GoogleSearch.Searchtool to perform a web search - -response = await client.tools.execute( -tool_name="GoogleSearch.Search", -input={"query": "Latest AI advancements"}, -) -print(response.output.value) - -```` - - -```javascript -import { Arcade } from "@arcadeai/arcadejs"; - -const client = new Arcade(api_key="arcade_api_key"); // or set the ARCADE_API_KEY env var - -// Use the GoogleSearch.Search tool to perform a web search -const response = await client.tools.execute({ - tool_name: "GoogleSearch.Search", - input: { query: "Latest AI advancements" }, -}); -console.log(response.output.value); -```` - - - diff --git a/app/en/home/auth/how-arcade-helps/page.mdx b/app/en/home/auth/how-arcade-helps/page.mdx deleted file mode 100644 index d6d63cd69..000000000 --- a/app/en/home/auth/how-arcade-helps/page.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "How Arcade helps" -description: "Learn how Arcade helps with auth and tool calling" ---- - -import { Tabs } from "nextra/components"; - -# How Arcade helps with Agent Authorization - -### The challenges that Arcade solves - -Applications that use models to perform tasks (_agentic applications_) commonly require access to sensitive data and services. Authentication complexities often hinder AI from performing tasks that require user-specific information, like what emails you recently received or what's coming up on your calendar. - -To retrieve this information, agentic applications need to be able to authenticate and authorize access to external services you use like Gmail or Google Calendar. - -Authenticating to retrieve information, however, is not the only challenge. Agentic applications also need to authenticate in order to **act** on your behalf - like sending an email or updating your calendar. - -Without auth, AI agents are severely limited in what they can do. - -### How Arcade solves this - -Arcade provides an authorization system that handles OAuth 2.0, API keys, and user tokens needed by AI agents to access external services through tools. This means your AI agents can now act on behalf of users securely and privately. - -With Arcade, developers can now create agents that can _act as the end users of their application_ to perform tasks like: - -- Creating a new Zoom meeting -- Sending or reading email -- Answering questions about files in Google Drive. - -### Auth permissions and scopes - -Each tool in Arcade's MCP Servers has a set of required permissions - or, more commonly referred to in OAuth2, **scopes**. For example, the [`Gmail.SendEmail`](/mcp-servers/productivity/gmail#gmailsendemail) tool requires the [`https://www.googleapis.com/auth/gmail.send`](https://developers.google.com/identity/protocols/oauth2/scopes#gmail) scope. - -A scope is what the user has authorized someone else (in this case, the AI agent) to do on their behalf. In any OAuth2-compatible service, each kind of action requires a different set of permissions. This gives the user fine-grained control over what data third-party services can access and what actions can be executed in their accounts. - -When a tool is called, the Arcade Engine will check if the user has granted the required permissions. If not, it will automatically prompt the user to authorize the tool, coordinating the OAuth2 flow with the service provider. - -### How to implement OAuth2-authorized tool calling - -To learn how Arcade allows for actions (tools) to be authorized through OAuth2 and how to implement it, check out [Authorized Tool Calling](/home/auth/auth-tool-calling). - -### Tools that don't require authorization - -Some tools, like [`GoogleSearch.Search`](/mcp-servers/search/google_search#googlesearchsearch), allow AI agents to retrieve information or perform actions without needing user-specific authorization. - - - -```python -from arcadepy import Arcade - -client = Arcade(api_key="arcade_api_key") # or set the ARCADE_API_KEY env var - -# Use the GoogleSearch.Searchtool to perform a web search - -response = await client.tools.execute( -tool_name="GoogleSearch.Search", -input={"query": "Latest AI advancements"}, -) -print(response.output.value) - -```` - - -```javascript -import { Arcade } from "@arcadeai/arcadejs"; - -const client = new Arcade(api_key="arcade_api_key"); # or set the ARCADE_API_KEY env var - -// Use the GoogleSearch.Search tool to perform a web search -const response = await client.tools.execute({ - tool_name: "GoogleSearch.Search", - input: { query: "Latest AI advancements" }, -}); -console.log(response.output.value); -```` - - - diff --git a/app/en/home/auth/secure-auth-production/page.mdx b/app/en/home/auth/secure-auth-production/page.mdx deleted file mode 100644 index cf7f07789..000000000 --- a/app/en/home/auth/secure-auth-production/page.mdx +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: "Secure Auth in Production" -description: "How to secure and brand your auth flows in production" ---- - -# Secure and Brand the Auth Flow in Production - -To keep your users safe, Arcade.dev performs a user verification check when a tool is authorized for the first time. This check verifies that the user who is authorizing the tool is the same user who started the authorization flow, which helps prevent phishing attacks. - -There are two ways to secure your auth flows with Arcade.dev: -- Use the **Arcade user verifier** for development (enabled by default) -- Implement a **custom user verifier** for production - -This setting is configured in the [Auth > Settings section](https://api.arcade.dev/dashboard/auth/settings) of the Arcade Dashboard. - - -## Use the Arcade user verifier - -If you're building a proof-of-concept app or a solo project, use the Arcade user verifier. This option requires no custom development and is on by default when you create a new Arcade.dev account. - -This setting is configured in the [Auth > Settings section](https://api.arcade.dev/dashboard/auth/settings) of the Arcade Dashboard: - -An image showing how to pick the Arcade user verifier option in the Arcade Dashboard - -When you authorize a tool, you'll be prompted to sign in to your Arcade.dev account. If you are already signed in (to the Arcade Dashboard, for example), this verification will succeed silently. - -The Arcade.dev user verifier helps keep your auth flows secure while you are building and testing your agent or app. When you're ready to share your work with others, implement a [custom user verifier](#build-a-custom-user-verifier) so your users don't need to sign in to Arcade.dev. - - - Arcade's default OAuth apps can *only* be used with the Arcade user verifier. - If you are building a multi-user production app, you must obtain your own OAuth app credentials and add them to Arcade. - For example, see our docs on [configuring Google auth in the Arcade Dashboard](/home/auth-providers/google#access-the-arcade-dashboard). - - -## Build a custom user verifier - -In a production application or agent, end-users are verified by your code, not Arcade.dev. This allows you to fully control the user experience of the auth flow. To enable this, build a custom verifier route and add the URL to the Arcade Dashboard. - -When your users authorize a tool, Arcade.dev will redirect the user's browser to your verifier route with some information in the query string. Your custom verifier route must send a response back to Arcade.dev to confirm the user's ID. - -If you need help, join the [Implementing a custom user verifier](https://github.com/ArcadeAI/arcade-ai/discussions/486) GitHub discussion and we'll be happy to assist. - -import { Steps, Tabs, Callout } from "nextra/components"; - - - -### Build a new route - -Create a public route in your app or API that can accept a browser redirect (HTTP 303) from Arcade.dev after a user has authorized a tool. - -The route must gather the following information: - -- The `flow_id` from the current URL's query string -- The unique ID of the user currently signed in, commonly an ID from your application's database, an email address, or similar. - -How the user's unique ID is retrieved varies depending on how your app is built, but it is typically retrieved from a session cookie or other secure storage. It **must** match the user ID that your code specified at the start of the authorization flow. - - -### Verify the user's identity - -Use the Arcade SDK (or our REST API) to verify the user's identity. - - - Because this request uses your Arcade API key, it *must not* be made from the client side (a browser or desktop app). This code must be run on a server. - - - - -```ts {13-16} -import { Arcade } from '@arcadeai/arcadejs'; - -const client = new Arcade(); // Looks for process.env.ARCADE_API_KEY by default - -// Within a server GET handler: -// Validate required parameters -if (!flow_id) { - throw new Error('Missing required parameters: flow_id'); -} - -// Confirm the user's identity -try { - const result = await client.auth.confirmUser({ - flow_id: flow_id as string, - user_id: user_id_from_your_app_session, // Replace with the user's ID - }); -} catch (error) { - console.error('Error during verification', 'status code:', error.status, 'data:', error.data); - throw error; -} -``` - - -```python {12-15} -from arcadepy import AsyncArcade - -client = AsyncArcade() # Looks for ARCADE_API_KEY environment variable by default - -# Within a server GET handler: -# Validate required parameters -if not flow_id: - raise Exception("Missing required parameters: flow_id") - -# Confirm the user's identity -try: - result = await client.auth.confirm_user( - flow_id=flow_id, - user_id=user_id_from_your_app_session, # Replace with the user's ID - ) -except Exception as error: - print("Error during verification:", error) - raise Exception("Failed to verify the request") -``` - - -```text -POST https://cloud.arcade.dev/api/v1/oauth/confirm_user -Authorization: Bearer -Content-Type: application/json - -{ - "flow_id": "", - "user_id": "" -} -``` - - - -**Valid Response** - -If the user's ID matches the ID specified at the start of the authorization flow, the response will contain some information about the auth flow. You can either: - -- Redirect the user's browser to Arcade's `next_uri` -- Redirect to a different route in your application -- Look up the auth flow's status in the Arcade API and render a success page - - - - -```ts -// Either redirect to result.next_uri, or render a success page: -const authResponse = await client.auth.waitForCompletion(result.auth_id); - -if (authResponse.status === "completed") { - return "Thanks for authorizing!"; -} else { - return "Something went wrong. Please try again."; -} -``` - - -```python -# Either redirect to result.next_uri, or render a success page: -auth_response = await client.auth.wait_for_completion(result.auth_id) - -if auth_response.status == "completed": - return "Thanks for authorizing!" -else: - return "Something went wrong. Please try again." -``` - - -```text -HTTP 200 OK -Content-Type: application/json - -{ - // Can be used to look up the auth flow's status in the Arcade API - "auth_id": "ac_2zKml...", - - // Optional: URL to redirect the user to after the authorization flow is complete - "next_uri": "https://..." -} -``` - - - - -**Invalid Response** - -If the user's ID does not match the ID specified at the start of the authorization flow, the response will contain an error. - - - -```ts -console.error('Error during verification', 'status code:', error.status, 'data:', error.data); -throw error; -``` - - -```python -print("Error during verification:", error) -raise Exception("Failed to verify the request") -``` - - -```text -HTTP 400 Bad Request -Content-Type: application/json - -{ - "code": 400, - "msg": "An error occurred during verification" -} -``` - - - -### Add your custom verifier route to Arcade - -In the [Auth > Settings section](https://api.arcade.dev/dashboard/auth/settings) of the Arcade Dashboard, pick the **Custom verifier** option and add the URL of your verifier route. - -An image showing how to pick the custom verifier option in the Arcade Dashboard - - - Arcade's default OAuth apps *only* support the Arcade user verifier. - Authorization flows using Arcade's default OAuth apps will use the Arcade user verifier even if you have a custom verifier route set up. - - - diff --git a/app/en/home/auth/tool-auth-status/page.mdx b/app/en/home/auth/tool-auth-status/page.mdx deleted file mode 100644 index ba9ed864e..000000000 --- a/app/en/home/auth/tool-auth-status/page.mdx +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: "Checking Tool Auth Status" -description: "Guide on checking the auth status of a tool" ---- - -# Checking Tool Authorization Status - -Before executing tools that require authorization, you can check their authorization status to understand what permissions are needed and whether they're currently available for a user. - -This is useful for: -- Displaying authorization requirements in your UI -- Pre-checking tool availability before execution -- Understanding which tools need user approval -- Debugging authorization issues - -import { Steps, Tabs, Callout } from "nextra/components"; - - -### Initialize the client - -Import the Arcade client in a Python/Javascript script. - - - -```python -from arcadepy import Arcade - -client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable -``` - - -```js -import Arcade from "@arcadeai/arcadejs"; - -const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable -``` - - - -### Check authorization status for all tools - -You can get a list of all available tools and check their authorization status for a specific user: - - - -```python -USER_ID = "{arcade_user_id}" - -# Get all tools for the user -tools = client.tools.list(user_id=USER_ID) - -for tool in tools: - print(f"Tool: {tool.name}") - - if tool.requirements: - # Check if all requirements are met - print(f"Requirements met: {tool.requirements.met}") - - # Check authorization status - if tool.requirements.authorization: - print(f"Authorization status: {tool.requirements.authorization.status}") - print(f"Token status: {tool.requirements.authorization.token_status}") - - # Check secret requirements - if tool.requirements.secrets: - for secret in tool.requirements.secrets: - print(f"Secret '{secret.key}' met: {secret.met}") - if not secret.met and secret.status_reason: - print(f"Reason: {secret.status_reason}") - - print("---") -``` - - -```js -const userId = "{arcade_user_id}"; - -// Get all tools for the user -const tools = await client.tools.list({ user_id: userId }); - -tools.items.forEach(tool => { - console.log(`Tool: ${tool.name}`); - - if (tool.requirements) { - // Check if all requirements are met - console.log(`Requirements met: ${tool.requirements.met}`); - - // Check authorization status - if (tool.requirements.authorization) { - console.log(`Authorization status: ${tool.requirements.authorization.status}`); - console.log(`Token status: ${tool.requirements.authorization.token_status}`); - } - - // Check secret requirements - if (tool.requirements.secrets) { - tool.requirements.secrets.forEach(secret => { - console.log(`Secret '${secret.key}' met: ${secret.met}`); - if (!secret.met && secret.status_reason) { - console.log(`Reason: ${secret.status_reason}`); - } - }); - } - } - - console.log("---"); -}); -``` - - - - -If a username is not provided, the Token Status will be excluded and only the requirements for the provider will be shown. - - -### Check authorization status for a specific tool - -You can also check the authorization status for a specific tool by name: - - - -```python -USER_ID = "{arcade_user_id}" -TOOL_NAME = "Gmail.ListEmails" - -# Get specific tool details -tool = client.tools.get(tool_name=TOOL_NAME, user_id=USER_ID) - -print(f"Tool: {tool.name}") -print(f"Description: {tool.description}") - -if tool.requirements: - print(f"All requirements met: {tool.requirements.met}") - - if tool.requirements.authorization: - auth = tool.requirements.authorization - print(f"Authorization required: {auth.provider_type}") - print(f"Authorization status: {auth.status}") - print(f"Token status: {auth.token_status}") - - if auth.status_reason: - print(f"Status reason: {auth.status_reason}") - - if tool.requirements.secrets: - print("Secret requirements:") - for secret in tool.requirements.secrets: - status = "✓" if secret.met else "✗" - print(f" {status} {secret.key}") -``` - - -```js -const userId = "{arcade_user_id}"; -const toolName = "Gmail.ListEmails"; - -// Get specific tool details -const tool = await client.tools.get(toolName, { - user_id: userId -}); - -console.log(`Tool: ${tool.name}`); -console.log(`Description: ${tool.description}`); - -if (tool.requirements) { - console.log(`All requirements met: ${tool.requirements.met}`); - - if (tool.requirements.authorization) { - const auth = tool.requirements.authorization; - console.log(`Authorization required: ${auth.provider_type}`); - console.log(`Authorization status: ${auth.status}`); - console.log(`Token status: ${auth.token_status}`); - - if (auth.status_reason) { - console.log(`Status reason: ${auth.status_reason}`); - } - } - - if (tool.requirements.secrets) { - console.log("Secret requirements:"); - tool.requirements.secrets.forEach(secret => { - const status = secret.met ? "✓" : "✗"; - console.log(` ${status} ${secret.key}`); - }); - } -} -``` - - - -### Understanding the status values - -#### Authorization Status -- `active`: If the provider is configured and enabled -- `inactive`: Authorization is not found or is disabled - -#### Token Status -- `not_started`: Authorization process hasn't begun -- `pending`: Authorization is in progress (user needs to approve) -- `completed`: Authorization is complete and tokens are available -- `failed`: Authorization process failed - -#### Requirements Met -- `true`: All requirements for the tool are satisfied -- `false`: Some requirements are missing (authorization, secrets, etc.) - -#### Secret Met -- `true`: The secret exists for the tool -- `false`: The secret does not exist for the tool diff --git a/app/en/home/build-tools/_meta.tsx b/app/en/home/build-tools/_meta.tsx deleted file mode 100644 index 88373013a..000000000 --- a/app/en/home/build-tools/_meta.tsx +++ /dev/null @@ -1,11 +0,0 @@ -export default { - "create-a-mcp-server": "Create an MCP Server", - "create-a-tool-with-auth": "Create a tool with auth", - "create-a-tool-with-secrets": "Create a tool with secrets", - "tool-context": "Tools and Context", - "organize-mcp-server-tools": "Organize MCP server tools", - "providing-useful-tool-errors": "Providing useful tool errors", - "retry-tools-with-improved-prompt": "Retry tools with improved prompt", - "call-tools-from-mcp-clients": "Call tools from MCP clients", - "migrate-from-toolkits": "Migrate from toolkits", -}; diff --git a/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx b/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx deleted file mode 100644 index c6873890f..000000000 --- a/app/en/home/build-tools/call-tools-from-mcp-clients/page.mdx +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: "Call tools from MCP clients" -description: "Learn how to call tools from MCP clients" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Call tools from MCP clients - - - - -Configure your MCP clients to call tools from your MCP server. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [Arcade CLI](/home/arcade-cli) -- [An MCP Server](/home/build-tools/create-a-mcp-server) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- How to configure your MCP clients depending on the transport type. -- How to set the secrets for your MCP server in your client's configuration file. - - - - -## Using the `arcade configure` command - -For popular MCP clients, you can use the `arcade configure` command to configure your MCP client to call your MCP server. This will automatically add the MCP server to your client's configuration file. By default, it will use the stdio transport. You must run this command from the directory of your entrypoint file. - - - - - ```bash - arcade configure cursor - ``` - - - - - ```bash - arcade configure vscode - ``` - - - - - ```bash - arcade configure claude - ``` - - - - -You can customize a lot of the configuration passing options to `arcade configure`. For example, to change the transport type to http, you can pass the `--transport` (or `-t`) option: - - - - - ```bash - arcade configure cursor --transport http - ``` - - - - - ```bash - arcade configure vscode --transport http - ``` - - - - - -Claude Desktop does not currently support the HTTP transport via JSON configuration files. - - - - - -### stdio specific configuration - -If you are using the stdio transport, `arcade configure` will assume the entrypoint file (the script that contains the `MCPApp` instance and calls `app.run()`) to your MCP server is `server.py` and will set the working directory to the path of your entrypoint file. You can override this with the `--entrypoint` (or `-e`) option: - - - Note that the `--entrypoint` accepts only the filename of the entrypoint - file, not the path to the script. - - - When using the stdio transport, `arcade configure` will automatically load the - secrets from the `.env` file at the directory of your entrypoint file into the appropriate - configuration file for your MCP client. - - - - - - ```bash - arcade configure cursor --entrypoint my_server.py - ``` - - - - - ```bash - arcade configure vscode --entrypoint my_server.py - ``` - - - - - ```bash - arcade configure claude --entrypoint my_server.py - ``` - - - - -### HTTP specific configuration - -If you are using the streamable HTTP transport, `arcade configure` will assume the MCP server is running on the default port `8000` and that the MCP server is running locally (in localhost). You can override this with the `--host` (or `-h`) and `--port` (or `-p`) options: - - - - - Run from a different port: - - ```bash - arcade configure cursor -t http --port 8000 - ``` - - If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option: - - ```bash - arcade configure cursor -t http --host arcade - ``` - - - - - Run from a different port: - - ```bash - arcade configure vscode -t http --port 8000 - ``` - - If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option: - - ```bash - arcade configure vscode -t http --host arcade - ``` - - - - - -Claude Desktop does not currently support the HTTP transport via JSON configuration files. - - - - - -### Other configuration options - -If you have modified the default configuration of your MCP client, or want to use a profile/workspace specific configuration file, then you can pass the `--config` (or `-c`) option to `arcade configure` to use your custom configuration file: - - - - - ```bash - arcade configure cursor --config /path/to/your/config.json - ``` - - - - - ```bash - arcade configure vscode --config /path/to/your/config.json - ``` - - - - - ```bash - arcade configure claude --config /path/to/your/config.json - ``` - - - - -By default, `arcade configure` will use the current directory as the name of the MCP server. You can override this with the `--name` (or `-n`) option: - - - - - ```bash - arcade configure cursor --name my_server - ``` - - - - - ```bash - arcade configure vscode --name my_server - ``` - - - - - ```bash - arcade configure claude --name my_server - ``` - - - - -## Manually configuring your MCP client - -If your MCP client is not supported by the `arcade configure` command, you can manually add the MCP server to your client's configuration file. - -Each MCP client has a different way of configuring MCP servers. This section covers the most common ways of configuring MCP servers adopted by the most popular MCP clients. However, you may find inconsistencies such as the need to specify the MCP server's type as its transport, or as "local" and "remote". Some MCP clients will use "env" to pass environment variables, while others may use "environment" or "inputs". Use this guide as a conceptual reference, but always refer to your MCP client's documentation for the most up-to-date information. - - - - -When configuring your MCP client using the stdio transport, you need to ensure that the MCP server is called using the right version of Python and within the correct working directory. For example, let's pretend this is your setup: - -- Your virtual environment is located at `/path/to/your/project/.venv` -- Your project is located at `/path/to/your/project` -- The entrypoint to your MCP server is located at `/path/to/your/server.py` -- One of your tools requires the `MY_SECRET_KEY` environment variable to be set. -- Your secrets are stored in the `/path/to/your/project/.env` file - -Then, your MCP client's configuration file should look like this: - -```json -{ - "mcpServers": { - "my_server": { - "command": "/path/to/your/project/.venv/bin/python", - "args": ["/path/to/your/project/server.py", "stdio"], - "env": { - "MY_SECRET_KEY": "my-secret-value" - } - } - } -} -``` - -This will ensure that the command used by the MCP client to start the MCP server is the correct version of Python and that the environment variables are set correctly. - - - - -When configuring your MCP client using the Streamable HTTP transport, ensure the MCP server is started on the correct port and from the correct working directory. For example, if your setup is: - -- Your virtual environment is located at `/path/to/your/project/.venv` -- Your MCP server is located at `/path/to/your/project/server.py` -- Your secrets are stored in the `/path/to/your/project/.env` file - -Activate the virtual environment: - -```bash -source /path/to/your/project/.venv/bin/activate -``` - -run the MCP server using the http transport. The secrets will be loaded from the `.env` file that is located at the directory of your entrypoint file: - -```bash -uv run server.py http -``` - -Then, your MCP client's configuration file should look like this: - -```json -{ - "mcpServers": { - "my_server": { - "url": "http://127.0.0.1:8000", - "transport": "http" - } - } -} -``` - - - For security reasons, Local HTTP servers do not currently support managed - authorization and secrets. If you need to use authorization or secrets, you - should use the stdio transport and configure the Arcade API key and secrets in - your MCP connection settings. If you intend to expose your HTTP MCP server to - the public internet, please follow the [on-prem MCP - server](/home/deployment/on-prem-mcp) guide for secure remote deployment. - - - - diff --git a/app/en/home/build-tools/create-a-mcp-server/page.mdx b/app/en/home/build-tools/create-a-mcp-server/page.mdx deleted file mode 100644 index c069316ed..000000000 --- a/app/en/home/build-tools/create-a-mcp-server/page.mdx +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: "Creating an MCP Server with Arcade" -description: "Learn how to create, test, deploy, and publish a custom MCP Server with Arcade" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Creating an MCP Server with Arcade - -The `arcade_mcp_server` package is the secure framework to build and run MCP servers with your Arcade tools. It is easiest to use with the `arcade-mcp` package (Arcade's CLI) which can scaffold your MCP server with all the necessary files and dependencies, configure MCP Clients to connect to your server, deploy your server to the cloud, and more. This guide walks you through the complete process of creating a custom MCP server with Arcade. - - - - -Build and run a secure MCP server with tools that you define. - - - - - -- The [`uv` package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- How to run MCP servers with Arcade tools using the [`arcade_mcp_server`](/references/mcp/python/overview) package -- How to use `arcade new` from the `arcade-mcp` CLI to create your server project with all necessary files and dependencies. -- How to run your local MCP Server with the Arcade CLI and register it with the Arcade Engine so that your agent can find and use your tool. - - - - - - -## Install the Arcade CLI - -In your terminal, run the following command to install the `arcade-mcp` package - Arcade's CLI: - - - - -```bash -uv tool install arcade-mcp -``` - -{" "} - - - This will install the Arcade CLI as a [uv - tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it - available system wide. - - - - - - -```bash -pip install arcade-mcp -``` - - - - -## Create Your Server - -In your terminal, run the following command to scaffold a new MCP Server called `my_server`: - -```bash -arcade new my_server -cd my_server/src/my_server -``` - -This generates a Python module with the following structure: - -```bash -my_server/ -├── src/ -│ └── my_server/ -│ ├── __init__.py -│ ├── .env.example -│ └── server.py -└── pyproject.toml -``` - -1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly. -1. **pyproject.toml** Dependencies and project configuration -1. **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.** - -```python filename="server.py" showLineNumbers -#!/usr/bin/env python3 -"""my_server MCP server""" - -import sys -from typing import Annotated - -import httpx -from arcade_mcp_server import Context, MCPApp -from arcade_mcp_server.auth import Reddit - -app = MCPApp(name="my_server", version="1.0.0", log_level="DEBUG") - - -@app.tool -def greet(name: Annotated[str, "The name of the person to greet"]) -> str: - """Greet a person by name.""" - return f"Hello, {name}!" - - -# To use this tool locally, you need to either set the secret in the .env file or as an environment variable -@app.tool(requires_secrets=["MY_SECRET_KEY"]) -def whisper_secret(context: Context) -> Annotated[str, "The last 4 characters of the secret"]: - """Reveal the last 4 characters of a secret""" - # Secrets are injected into the context at runtime. - # LLMs and MCP clients cannot see or access your secrets - # You can define secrets in a .env file. - try: - secret = context.get_secret("MY_SECRET_KEY") - except Exception as e: - return str(e) - - return "The last 4 characters of the secret are: " + secret[-4:] - -# To use this tool locally, you need to install the Arcade CLI (uv tool install arcade-mcp) -# and then run 'arcade login' to authenticate. -@app.tool(requires_auth=Reddit(scopes=["read"])) -async def get_posts_in_subreddit( - context: Context, subreddit: Annotated[str, "The name of the subreddit"] -) -> dict: - """Get posts from a specific subreddit""" - # Normalize the subreddit name - subreddit = subreddit.lower().replace("r/", "").replace(" ", "") - - # Prepare the httpx request - # OAuth token is injected into the context at runtime. - # LLMs and MCP clients cannot see or access your OAuth tokens. - oauth_token = context.get_auth_token_or_empty() - headers = { - "Authorization": f"Bearer {oauth_token}", - "User-Agent": "finally-mcp-server", - } - params = {"limit": 5} - url = f"https://oauth.reddit.com/r/{subreddit}/hot" - - # Make the request - async with httpx.AsyncClient() as client: - response = await client.get(url, headers=headers, params=params) - response.raise_for_status() - - # Return the response - return response.json() - -# Run with specific transport -if __name__ == "__main__": - # Get transport from command line argument, default to "stdio" - # - "stdio" (default): Standard I/O for Claude Desktop, CLI tools, etc. - # Supports tools that require_auth or require_secrets out-of-the-box - # - "http": HTTPS streaming for Cursor, VS Code, etc. - # Does not support tools that require_auth or require_secrets unless the server is deployed - # using 'arcade deploy' or added in the Arcade Developer Dashboard with 'Arcade' server type - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - # Run the server - app.run(transport=transport, host="127.0.0.1", port=8000) -``` - -## Setup the secrets in your environment - -Secrets are sensitive strings like passwords, API keys, or other tokens that grant access to a protected resource or API. Arcade includes the "whisper_secret" tool that requires a secret key to be set in your environment. If the secret is not set, the tool will return an error. - - - -You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret: - -```env filename=".env" -MY_SECRET_KEY="my-secret-value" -``` - -The generated project includes a `.env.example` file with the secret key name and example value. -You can rename it to `.env` to start using it. - -```bash -mv .env.example .env -``` - - - -You can set the environment variable in your terminal directly with this command: - -```bash -export MY_SECRET_KEY="my-secret-value" -``` - - - - -## Connect to Arcade to unlock authorized tool calling - -Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run: - -```bash -arcade login -``` - -Follow the instructions in your browser, and once you've finished, your terminal will be connected to your Arcade account. - -## Run your MCP Server - -Run your MCP Server using one of the following commands in your terminal: - - - - - -```bash -uv run server.py stdio -``` - - - When using the stdio transport, MCP clients typically launch the MCP server as - a subprocess. Because of this, the server may run in a different environment - and not have access to secrets defined in your local `.env` file. Please refer - to the [create a tool with - secrets](/home/build-tools/create-a-tool-with-secrets) guide for more - information. - - - - - -```bash -uv run server.py http -``` - -For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). - - - For security reasons, Local HTTP servers do not currently support tool-level - authorization and secrets. If you need to use tool-level authorization or - secrets locally, you should use the stdio transport and configure the Arcade - API key and secrets in your MCP connection settings. Otherwise, if you intend - to expose your HTTP MCP server to the public internet with tool-level - authorization and secrets, please follow the [deploying to the cloud with - Arcade Deploy](/home/serve-tools/arcade-deploy) guide or the [on-prem MCP - server](/home/deployment/on-prem-mcp) guide for secure remote deployment. - - - - - -You should see output like this in your terminal: - -```bash -2025-11-03 13:46:11.041 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet -2025-11-03 13:46:11.042 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret -2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit -INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools -``` - -## Configure your MCP Client(s) - -Now you can connect MCP Clients to your MCP server: - - - - - ```bash - # Configure Cursor to use your MCP server with the default transport (stdio) - arcade configure cursor - - # Configure Cursor to use your MCP server with the http transport - arcade configure cursor --transport http - ``` - - - - - ```bash - # Configure VS Code to use your MCP server with the default transport (stdio) - arcade configure vscode - - # Configure VS Code to use your MCP server with the http transport - arcade configure vscode --transport http - ``` - - - - - ```bash - # Configure Claude Desktop to use your MCP server with the default transport (stdio) - arcade configure claude - - # Configure Claude Desktop to use your MCP server with the http transport - arcade configure claude --transport http - ``` - - - - -That's it! Your MCP server is running and connected to your AI assistant. - - - -## Key takeaways - -- **Minimal Setup** Create `MCPApp`, define tools with `@app.tool`, and run with `app.run()` -- **Direct Execution** Run your server file directly with `uv run` or `python` -- **Transport Flexibility** Works with both stdio and HTTP -- **Type Annotations** Use `Annotated` from the builtin typing library to provide descriptions to the language model for parameters and return values -- **Tool Docstrings** Use docstrings to provide a description of a tool to the language model -- **Command Line Arguments** Pass transport type as command line argument - -### Next steps - -- **Create custom tools that use auth**: [Learn how to create tools with authorization](/home/build-tools/create-a-tool-with-auth) -- **Create custom tools that use secrets**: [Learn how to create tools with secrets](/home/build-tools/create-a-tool-with-secrets) -- **Learn the capabilities of the `Context` object**: [Understanding the Context object](/home/build-tools/tool-context) -- **Evaluate your tools**: [Explore how to evaluate tool performance](/home/evaluate-tools/why-evaluate-tools) -- **Deploy your MCP server**: [Learn how to deploy your MCP server](/home/serve-tools/arcade-deploy) diff --git a/app/en/home/build-tools/create-a-tool-with-auth/page.mdx b/app/en/home/build-tools/create-a-tool-with-auth/page.mdx deleted file mode 100644 index 7b1b3e0b0..000000000 --- a/app/en/home/build-tools/create-a-tool-with-auth/page.mdx +++ /dev/null @@ -1,338 +0,0 @@ ---- -title: "Add user authorization to your MCP tools" -description: "Learn how to build custom MCP tools that require user authorization using Arcade, auth providers, and OAuth." ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Add user authorization to your MCP tools - - - - -Create and use an MCP tool that requires OAuth to access Reddit, prompting users to authorize the action when called. Jump to [Example Code](#example-code) to see the complete code. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) -- [Create an MCP Server](/home/build-tools/create-a-mcp-server) - - - - - -- How auth providers work. -- How to add user authorization to your custom tools with Arcade. -- How to use the Context to make authenticated requests to external APIs. -- How to use the Reddit auth provider to authorize your tool. - - - - -An auth provider is the service that issues and manages the OAuth token your tool uses. It is the identity “source of truth” your tool integrates with to request permissions and obtain OAuth tokens. - -When you create a tool with `requires_auth`, you specify which provider to use. In this example, **`arcade_mcp_server.auth.Reddit` specifies the Reddit auth provider.** - -## How auth providers work during execution - -1. When the tool is invoked, Arcade checks if the user has already authorized the scopes required by the tool. -2. If the tool's requirements are not met, Arcade initiates the provider-specific OAuth flow for the requested scopes. - > 2a). The user is presented with a URL to complete the OAuth challenge. The user will need to visit this URL and log in and explicitly grant consent for the action to be performed on their behalf. This is the "OAuth challenge". - - > 2b). The provider issues the token, and Arcade will securely inject it into the tool's [`Context`](/home/build-tools/tool-context) on its next invocation. The client and the LLM will never see the token. - - > 2c). The tool needs to be re-invoked - this time its requirements will be met. -3. The tool is executed, and uses the token injected into its `Context` to call the provider's API (e.g., `https://oauth.reddit.com`), without the LLM or client ever seeing the token. - -The auth provider defines where the identity lives, what permissions are available (scopes), and how tokens are issued and refreshed. In code, it's the class you pass to `requires_auth` (e.g., `Reddit(scopes=["read"])`) that encodes the OAuth details for that service. - -## Add user authorization to your MCP tools - - - -### Import the necessary modules - -Create a new Python file, e.g., `auth_tools.py`, and import the necessary modules and classes: - -```python showLineNumbers filename="auth_tools.py" -import sys -from typing import Annotated - -import httpx -from arcade_mcp_server import Context, MCPApp -from arcade_mcp_server.auth import Reddit -``` - -### Create the MCP Server - -Create an instance of the `MCPApp` class: - -```python filename="auth_tools.py" -app = MCPApp(name="auth_example", version="1.0.0", log_level="DEBUG") -``` - -### Define your MCP tool - -Now, define your tool using the `@app.tool` decorator and specify the required authorization, in this case, by using [Arcade's Reddit auth provider](/home/auth-providers/reddit). - -Specifying the `requires_auth` parameter in the `@app.tool` decorator indicates that the tool needs user authorization. In this example, we're using the `Reddit` auth provider with the `read` scope: - -```python showLineNumbers filename="auth_tools.py" {1-5} {16} -@app.tool( - requires_auth=Reddit( - scopes=["read"] - ) -) -async def get_posts_in_subreddit( - context: Context, subreddit: Annotated[str, "The name of the subreddit"] -) -> dict: - """Get posts from a specific subreddit""" - # Normalize the subreddit name - subreddit = subreddit.lower().replace("r/", "").replace(" ", "") - - # Prepare the httpx request - # OAuth token is injected into the context at runtime. - # LLMs and MCP clients cannot see or access your OAuth tokens. - oauth_token = context.get_auth_token_or_empty() - headers = { - "Authorization": f"Bearer {oauth_token}", - "User-Agent": "mcp_server-mcp-server", - } - params = {"limit": 5} - url = f"https://oauth.reddit.com/r/{subreddit}/hot" - - # Make the request - async with httpx.AsyncClient() as client: - response = await client.get(url, headers=headers, params=params) - response.raise_for_status() - - # Return the response - return response.json() -``` - - - -To use this tool, you need to install the Arcade CLI and run 'arcade login' to authenticate: - -```bash -uv tool install arcade-mcp -arcade login -``` - - - -Arcade offers a number of [built-in auth providers](/home/auth-providers), including Slack, Google, and GitHub. You can also require authorization with a custom auth provider, using the `OAuth2` class, a subclass of the `ToolAuthorization` class: - -```python -@app.tool( - requires_auth=OAuth2( - id="your-oauth-provider-id", - scopes=["scope1", "scope2"], - ) -) -``` - - - The `OAuth2` class requires an `id` parameter to identify the auth provider in - the Arcade Engine. For built-in providers like `Slack`, you can skip the `id`. - The Arcade Engine will find the right provider using your credentials. While - you can specify an `id` for built-in providers, only do this for private tools - that won't be shared. - - -### Specify OAuth scopes - -Specify the OAuth scopes you need for your tool. In this example, you already are using the `read` scope, but you can specify multiple scopes for more permissions (like `identity`): - -```python showLineNumbers filename="auth_tools.py" {2} -# Multiple scopes for more permissions -@app.tool(requires_auth=Reddit(scopes=["read", "identity"])) -async def identity_tool(context: Context) -> dict: - """Tool that accesses user identity.""" - pass -``` - - -Scopes are defined by the auth provider, and they vary between providers. Each service exposes its own set of scopes that determine what your tools can access. You'll need to review the provider's documentation to see which scopes are available and what permissions each one grants. - - -### Run the MCP Server - -```python showLineNumbers filename="auth_tools.py" -if __name__ == "__main__": - # Get transport from command line argument, default to "stdio" - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - print(f"Starting auth example server with {transport} transport") - print("Prerequisites:") - print(" 1. Install: uv tool install arcade-mcp") - print(" 2. Login: arcade login\n") - - # Run the server - # - "stdio" (default): Standard I/O transport - # - "http": HTTP streamable transport - app.run(transport=transport, host="127.0.0.1", port=8000) -``` - -Verify your MCP Server can run successfully by executing the following command in your terminal: - -```bash -uv run auth_tools.py stdio -``` - -## Configure your MCP Client(s) - -Now you can connect your MCP server to apps that support MCP Clients, like AI assistants and IDEs. : - - - - - ```bash - arcade configure claude - ``` - - - - - ```bash - arcade configure cursor - ``` - - - - - ```bash - arcade configure vscode - ``` - - - - -Now restart your MCP Client and try calling your tool. - -### Handle authorization - -Since the tool requires authorization, the first time a user uses it, the user will go through an OAuth flow to authorize the tool to act on their behalf. Once the user has completed the OAuth flow, the tool will need to be re-invoked. See the [how auth providers work during execution](#how-auth-providers-work-during-execution) section for more details. - - - -## How it works - -Arcade manages the OAuth flow, and provides the token via `context.get_auth_token_or_empty()`. Arcade also remembers the user's authorization tokens, so they won't have to go through the authorization process again until the token is revoked by the user. - -### Accessing OAuth tokens - -To get the authorization token, use the `context.get_auth_token_or_empty()` method. - -```python filename="auth_tools.py" -# Get the token (returns empty string if not authenticated) -oauth_token = context.get_auth_token_or_empty() - -# Use token in API requests -headers = { - "Authorization": f"Bearer {oauth_token}", - "User-Agent": "my-app", -} -``` - -### Making Authenticated API Requests - -Use the OAuth token with httpx or other HTTP clients: - -```python filename="auth_tools.py" -import httpx - -async with httpx.AsyncClient() as client: - response = await client.get( - "https://oauth.reddit.com/api/endpoint", - headers={"Authorization": f"Bearer {oauth_token}"} - ) - response.raise_for_status() - return response.json() -``` - -## Security Best Practices - -- Never log tokens: OAuth tokens should never be logged or exposed -- Use appropriate scopes: Request only the scopes your tool actually needs - -## Key takeaways - -- **OAuth Support:** Arcade handles OAuth flows and token management -- **Secure Token Injection:** Tokens are injected into context at runtime -- **Scope Management:** Specify exactly which permissions your tool needs -- **Provider Support:** Multiple OAuth providers available out of the box -- **User Privacy:** LLMs and MCP clients never see OAuth tokens - -## Next steps - -- Try adding more authorized tools -- Explore how to handle different authorization providers and scopes -- Learn how to [build a tool with secrets](/home/build-tools/create-a-tool-with-secrets) - -## Example Code - -```python showLineNumbers filename="auth_tools.py" -#!/usr/bin/env python3 -import sys -from typing import Annotated - -import httpx -from arcade_mcp_server import Context, MCPApp -from arcade_mcp_server.auth import Reddit - -# Create the app -app = MCPApp(name="auth_example", version="1.0.0", log_level="DEBUG") - - -# To use this tool, you need to use the Arcade CLI (uv pip install arcade-mcp) -# and run 'arcade login' to authenticate. -@app.tool(requires_auth=Reddit(scopes=["read"])) -async def get_posts_in_subreddit( - context: Context, subreddit: Annotated[str, "The name of the subreddit"] -) -> dict: - """Get posts from a specific subreddit""" - # Normalize the subreddit name - subreddit = subreddit.lower().replace("r/", "").replace(" ", "") - - # Prepare the httpx request - # OAuth token is injected into the context at runtime. - # LLMs and MCP clients cannot see or access your OAuth tokens. - oauth_token = context.get_auth_token_or_empty() - headers = { - "Authorization": f"Bearer {oauth_token}", - "User-Agent": "mcp_server-mcp-server", - } - params = {"limit": 5} - url = f"https://oauth.reddit.com/r/{subreddit}/hot" - - # Make the request - async with httpx.AsyncClient() as client: - response = await client.get(url, headers=headers, params=params) - response.raise_for_status() - - # Return the response - return response.json() - - -if __name__ == "__main__": - # Get transport from command line argument, default to "stdio" - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - print(f"Starting auth example server with {transport} transport") - print("Prerequisites:") - print(" 1. Install: uv tool install arcade-mcp") - print(" 2. Login: arcade login\n") - - # Run the server - # - "stdio" (default): Standard I/O transport - # - "http": HTTP streamable transport - app.run(transport=transport, host="127.0.0.1", port=8000) - -``` diff --git a/app/en/home/build-tools/create-a-tool-with-secrets/page.mdx b/app/en/home/build-tools/create-a-tool-with-secrets/page.mdx deleted file mode 100644 index 18c347df8..000000000 --- a/app/en/home/build-tools/create-a-tool-with-secrets/page.mdx +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: "Create an MCP tool with secrets" -description: "Learn how to build custom MCP tools that require secrets using Arcade" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Create an MCP tool with secrets - - - - -Build an MCP tool that can read a secret from Context and return a masked confirmation string. Jump to [Example Code](#example-code) to see the complete code. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [Arcade CLI](/home/quickstart) -- [An MCP Server](/home/build-tools/create-a-mcp-server) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- How to read secrets from environment and `.env` files securely using a tool's Context. -- How to configure secrets in the Arcade Dashboard. - - - - -Secrets are sensitive strings like passwords, API keys, or other tokens that grant access to a protected resource or API. You can also use secrets to provide other static configuration values your tool needs, such as parameters for calling a remote API. - -## Why use secrets in your tools? - -Secrets enable you to securely deploy a function that requires sensitive information at runtime. And while these can be consumed directly from the runtime environment inside your tool function, this becomes very inconvenient, expensive, hard to maintain, and insecure when deploying at scale. - -For example, if your tool requires an API key to use an external service, but only _after_ doing some computationally expensive work, you need to ensure that the API key is present _before_ the computationally expensive work is done. The function below would fail if the API key is not present. - -```python -import os - -def my_tool(task: str) -> str: - result = expensive_computation(task) - - API_KEY = os.getenv("API_KEY") - - # The line below will fail if the API key is not present - success = upload_result_to_service(result, API_KEY) - - if success: - return "Result uploaded successfully" - else: - return "Failed to upload result" -``` - -We can work around this by carefully checking for the API key before doing the computationally expensive work, of course, but this is error prone and difficult to maintain, and you may only become aware of the issue after deploying multiple instances of your server. - -Arcade provides a way to securely store and access secrets inside your tools in a way that is easy to manage across multiple instances of your servers, and that will prevent the tool from running if the secret is not provided. In this guide, you'll learn how to use secrets in your custom Arcade tools. - - - -## Store your secret - -Depending on where you're running your server, you can store your secret in a few different ways. - - - -You can create a `.env` file in the same directory as your entrypoint file (typically `server.py` by default) and add your secret: - -```env filename=".env" -MY_SECRET_KEY="my-secret-value" -``` - -The project includes a `.env.example` file with the secret key name and example value. -You can rename it to `.env` to start using it. - -```bash -mv .env.example .env -``` - - - Using a `.env` file is okay for local development, but you should use - the Arcade Dashboard or Arcade CLI for production deployments. - - - - -You can store your secret in the Arcade Dashboard by: - -- Navigating to the "Secrets" section of the Arcade Dashboard -- Clicking the "Add Secret" button -- Entering the secret ID and value -- Clicking the "Create" button - -This will make the secret available to your MCP server, when deployed to Arcade. - - - The Arcade Dashboard will make the secret available to your MCP server when it is deployed. Secrets set in the Arcade Dashboard are not available to your MCP server when it is running locally. - - - - -You can set the secret in your terminal directly with this command: - -```bash -arcade secret set MY_SECRET_KEY="my-secret-value" -``` - - - The Arcade CLI will make the secret available to your MCP server when it is deployed, because it upserts the secret into the Arcade Cloud. Secrets set in the Arcade CLI are not available to your MCP server when it is running locally. - - - - -You can set the environment variable in your terminal directly with this command: - -```bash -export MY_SECRET_KEY="my-secret-value" -``` - - - Using environment variables is okay for local development, but you should use - the Arcade Dashboard or Arcade CLI for production deployments. - - - - - -### Using secrets with stdio transport - -When using the stdio transport, MCP clients typically launch the MCP server as a subprocess. Because of this, the server may run in a different environment and not have access to secrets defined in your local `.env` file or your terminal environment variables. - -To ensure your stdio MCP server has access to the secrets, you can either -1. Utilize the [`arcade configure` CLI command](/home/arcade-cli#arcade-configure) to configure your MCP client to pass the secrets to your MCP server, or -2. Manually configure your MCP client to pass the secrets to your MCP server. For example, if you are using Cursor IDE, you can add the following to your `mcp.json` file: - - ```json - { - "mcpServers": { - "simple": { - "command": "uv", - "args": [ - "run", - "--directory", - "/absoulute/path/to/your/entrypoint/file/parent/directory", - "python", - "server.py" - ], - "env": { - "MY_SECRET_KEY": "my-secret-value" - } - } - } - } - ``` - -This will make the secret available to your MCP server when the MCP client starts the subprocess. -Note that the specific key name may vary depending on the MCP client you are using. - -### Define your tool and access the secret - - - This is only an illustrative example of how Arcade will ensure that the secret - is present before the tool is executed. In a real world application, you would - use this secret to store sensitive information like API keys, database - credentials, etc, and not to simply print a confirmation string. - - -In your [MCP Server](/home/build-tools/create-a-mcp-server), create a new tool that uses the secret: - -- Use the `requires_secrets` parameter to declare which secrets your tool needs (`"SECRET_KEY"` in this example). -- The tool's Context object has a `get_secret` method that you can use to access the secret value. - -```python filename="secrets.py" showLineNumbers highlightLines={2,4,7} -@app.tool( - requires_secrets=["SECRET_KEY"], # declare we need SECRET_KEY -) -def use_secret(context: Context) -> str: - """Read SECRET_KEY from context and return a masked confirmation string.""" - try: - value = context.get_secret("SECRET_KEY") - masked = value[:2] + "***" if len(value) >= 2 else "***" - return f"Got SECRET_KEY of length {len(value)} -> {masked}" - except ValueError as e: - return f"Error getting secret: {e}" -``` - -When your tool is executed, it will return: `"Got SECRET_KEY of length..."`. In a real world application, you would use this secret to connect to a remote database, API, etc. - - - - - -**Security Best Practices** - -- **Never log secret values:** Always mask or truncate when displaying -- **Declare requirements:** Use `requires_secrets` to document dependencies -- **Handle missing secrets:** Use try/except when accessing secrets -- **Use descriptive names:** Make it clear what each secret is for - - - -## Key Concepts - -- **Secure Access:** Secrets are accessed through context, not imported directly -- **Environment Integration:** Works with both environment variables and .env files -- **Error Handling:** Always handle the case where a secret might be missing -- **Masking:** Never expose full secret values in logs or return values -- **Declaration:** Use `requires_secrets` to make dependencies explicit - -## Example Code - -### Environment Variables - -```env filename=".env" -SECRET_KEY="supersecret" -``` - - - -For the code to work, you must define your environment variables locally or in a `.env` file. - - - -```python filename="secrets.py" -#!/usr/bin/env python3 -import sys - -from arcade_mcp_server import Context, MCPApp - -# Create the MCP application -app = MCPApp( - name="secrets_example", - version="1.0.0", - instructions="Example server demonstrating secrets usage", -) - - -@app.tool( - requires_secrets=["SECRET_KEY"], # declare we need SECRET_KEY -) -def use_secret(context: Context) -> str: - """Read SECRET_KEY from context and return a masked confirmation string.""" - try: - value = context.get_secret("SECRET_KEY") - masked = value[:2] + "***" if len(value) >= 2 else "***" - return f"Got SECRET_KEY of length {len(value)} -> {masked}" - except ValueError as e: - return f"Error getting secret: {e}" - - -if __name__ == "__main__": - # Get transport from command line argument, default to "stdio" - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - # Run the server - app.run(transport=transport, host="127.0.0.1", port=8000) -``` - -### Run your MCP server - - - - -```bash -uv run secrets.py stdio -``` - - - - -```bash -uv run secrets.py http -``` - -For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). - - - For security reasons, Local HTTP servers do not currently support tool-level - authorization and secrets. If you need to use tool-level authorization or secrets locally, you - should use the stdio transport and configure the Arcade API key and secrets in - your MCP connection settings. Otherwise, if you intend to expose your HTTP MCP server to - the public internet with tool-level authorization and secrets, please follow the [deploying to the cloud with Arcade Deploy](/home/serve-tools/arcade-deploy) guide or the [on-prem MCP - server](/home/deployment/on-prem-mcp) guide for secure remote deployment. - - - - - diff --git a/app/en/home/build-tools/migrate-from-toolkits/page.mdx b/app/en/home/build-tools/migrate-from-toolkits/page.mdx deleted file mode 100644 index ac5905e62..000000000 --- a/app/en/home/build-tools/migrate-from-toolkits/page.mdx +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: "Migrate from toolkits to MCP servers" -description: "Learn how to migrate your existing Arcade toolkit to the new MCP Server framework" ---- - -import { Steps, Callout } from "nextra/components"; - -# Migrate from toolkits to MCP servers - -This guide helps you migrate your existing Arcade toolkit to the new MCP Server framework. The `arcade-tdk` package has been deprecated in favor of `arcade-mcp-server`, and the `arcade-ai` CLI has been replaced by `arcade-mcp`. - - - If you're building a new MCP server from scratch, check out the [Create an MCP - Server](/home/build-tools/create-a-mcp-server) guide instead. - - - If you're migrating an existing toolkit to a new MCP server, it may be useful - to read through our quickstart guide to get a sense of the new MCP Server - framework: [Create an MCP Server](/home/build-tools/create-a-mcp-server) - - -## Understanding the changes - -Before migrating, it's helpful to understand what has changed: - -### Terminology updates - -- **Workers** are now called **servers** or **MCP servers** -- **Toolkits** are now called **servers**, **MCP servers**, or **tools** depending on the context - -### Package changes - -- **arcade-ai** (old CLI) → **arcade-mcp** (new CLI) -- **arcade-tdk** (old tool development kit) → **arcade-mcp-server** (new MCP Server framework) - -The new `arcade-mcp-server` framework should feel familiar if you've used `arcade-tdk`, but there are important differences to be aware of. - - - -## Update your dependencies - -Open your `pyproject.toml` file and update the dependencies: - -### Replace the main dependency - -Replace `arcade-tdk` with `arcade-mcp-server`: - -```toml -[project] -dependencies = [ - "arcade-mcp-server>=1.4.0,<2.0.0", - # ... other dependencies -] -``` - -### Update development dependencies - -If your toolkit used `arcade-ai` or `arcade-serve` as development dependencies, replace them with `arcade-mcp[all]`: - -```toml -[project.optional-dependencies] -dev = [ - "arcade-mcp[all]>=1.3.0,<2.0.0", - # ... other dev dependencies -] -``` - -### Install the updated dependencies - -Run the following command to install the updated dependencies and development dependencies: - -```bash -uv sync --extra dev -``` - -## Update your imports - -Replace all imports from `arcade-tdk` with imports from `arcade-mcp-server`. Most import paths have remained the same or have only slight variations: - -### Auth imports - -```python -# Before -from arcade_tdk.auth import Google - -# After -from arcade_mcp_server.auth import Google -``` - -### Tool decorator - -```python -# Before -from arcade_tdk import tool - -# After -from arcade_mcp_server import tool -``` - -### Error handling - -```python -# Before -from arcade_tdk.errors import ToolExecutionError - -# After -from arcade_mcp_server.exceptions import ToolExecutionError -``` - -### Context object - -Replace `ToolContext` with `Context`: - -```python -# Before -from arcade_tdk import ToolContext - -@tool -def my_tool(context: ToolContext) -> str: - """My tool that uses context""" - return "Hello" - -# After -from arcade_mcp_server import Context - -@tool -def my_tool(context: Context) -> str: - """My tool that uses context""" - return "Hello" -``` - - - The `ToolContext` class is no longer used. Make sure to replace all instances - of `ToolContext` with `Context` in your tool functions. - - -## Create an entrypoint file - -Previously, you would run your toolkit using the `arcade serve` CLI command. Now, you need to create an entrypoint file that runs your MCP server. This allows you to define your own startup and teardown logic for your MCP server. - -An entrypoint file is a Python file that creates and runs an `MCPApp` when invoked. `MCPApp` is the developer-facing API for creating and managing your MCP server. - -### Option 1: Use the tool decorator - -You can register tools directly on the app using the `@app.tool` decorator: - -```python -#!/usr/bin/env python3 -"""My MCP Server""" - -import sys -from arcade_mcp_server import MCPApp - -app = MCPApp(name="my_server", version="1.0.0") - -@app.tool -def echo_hello() -> str: - """Tool that just says hello""" - return "Hello" - -@app.tool -def echo_goodbye() -> str: - """Tool that just says goodbye""" - return "Goodbye" - -if __name__ == "__main__": - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - app.run(transport=transport) -``` - -### Option 2: Register tools explicitly - -You can also use the standalone `@tool` decorator and register tools explicitly: - -```python -#!/usr/bin/env python3 -"""My MCP Server""" - -import sys -from arcade_mcp_server import MCPApp, tool - -@tool -def echo_hello() -> str: - """Tool that just says hello""" - return "Hello" - -@tool -def echo_goodbye() -> str: - """Tool that just says goodbye""" - return "Goodbye" - -app = MCPApp(name="my_server", version="1.0.0") -app.add_tool(echo_hello) -app.add_tool(echo_goodbye) - -if __name__ == "__main__": - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - app.run(transport=transport) -``` - -### Option 3: Register tools from modules - -If your old toolkit had many tools, you may want to use the `add_tools_from_module` method to register all your tools at once: - -```python -#!/usr/bin/env python3 -"""My MCP Server""" - -import sys -import my_module_with_tools - -from arcade_mcp_server import MCPApp - -app = MCPApp(name="my_server", version="1.0.0") -app.add_tools_from_module(my_module_with_tools) - -if __name__ == "__main__": - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - app.run(transport=transport) -``` - - - For large toolkits with many tools, using `add_tools_from_module` is the - recommended approach. This keeps your entrypoint file clean and maintainable. - - -## Run your MCP server - -Replace the old `arcade serve` command with direct execution of your entrypoint file: - -```bash -# Before -arcade serve - -# After -uv run server.py -``` - -You can specify the transport type as a command line argument: - -```bash -# Run with stdio transport (default) -uv run server.py stdio - -# Run with HTTP transport -uv run server.py http -``` - -## Update deployment configuration - -The `arcade deploy` command still exists for deploying MCP servers, but the deployment process has been simplified. - -### Before (with toolkits) - -Previously, you would deploy your toolkit using: - -```bash -arcade deploy -``` - -And configure your deployment with a `worker.toml` file. - -### After (with MCP servers) - -You still use `arcade deploy`, but you no longer need a `worker.toml` file: - -```bash -arcade deploy -``` - -The deployment configuration is now inferred from your `MCPApp` and project structure. - - - You're no longer deploying a "worker" you're deploying an MCP server. The - deployment process has been streamlined to require less configuration. - - - - -## Quick reference - -Here's a quick reference table for common changes: - -| Old (toolkit) | New (MCP server) | -| -------------------------------------------------- | ------------------------------------------------------------- | -| `arcade-tdk` | `arcade-mcp-server` | -| `arcade-ai` | `arcade-mcp` | -| `arcade serve` | `uv run server.py` | -| `from arcade_tdk import tool` | `from arcade_mcp_server import tool` | -| `from arcade_tdk import ToolContext` | `from arcade_mcp_server import Context` | -| `from arcade_tdk.errors import ToolExecutionError` | `from arcade_mcp_server.exceptions import ToolExecutionError` | -| `worker.toml` | Not needed | - -## Next steps - -After migrating your toolkit to an MCP server: - -- **Test your server**: Run your server locally and verify all tools work correctly -- **Update your CI/CD**: Update any automated workflows to use the new CLI and commands -- **Deploy your server**: Use `arcade deploy` to deploy your MCP server -- **Configure MCP clients**: Connect your server to [MCP clients](/home/build-tools/call-tools-from-mcp-clients) like Claude Desktop, Cursor, or VS Code diff --git a/app/en/home/build-tools/organize-mcp-server-tools/page.mdx b/app/en/home/build-tools/organize-mcp-server-tools/page.mdx deleted file mode 100644 index 92574b4d5..000000000 --- a/app/en/home/build-tools/organize-mcp-server-tools/page.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: "Organize your MCP server and tools" -description: "Learn best practices for organizing your MCP server and tools, how to import tools from other packages and how to use them together." ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Organize your MCP server and tools - - - - -Learn best practices for organizing your MCP server and tools, how to import tools from other packages and how to use them together. Jump to [Example Code](#example-code) to see the complete code. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [An MCP Server](/home/build-tools/create-a-mcp-server) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- How to define tools in separate files and import them -- How to import tools from other Arcade packages -- How to use `@app.tool` decorators and imported tools together - - - - -## Project Structure - -We recommend keeping your MCP server file and tools in separate files in a `tools` directory like so: - -```bash - my_server/ - ├── src/ - │ └── my_server/ - │ ├── .env - │ ├── server.py # Entrypoint file with your MCPApp - │ ├── tools/ - │ │ ├── __init__.py - │ │ ├── math_tools.py # @tool decorated functions - │ │ └── text_tools.py # @tool decorated functions - │ ├── pyproject.toml - │ └── README.md - └── pyproject.toml -``` - -## Defining tools - -You can use the `@app.tool` decorator to define your tools in your MCP server file directly on the MCP server app object (`MCPApp`) like this: - -```python filename="server.py" -@app.tool -def server_info() -> Annotated[dict, "Information about this server"]: - """Return information about this MCP server.""" - return { - "name": "Organized Server", - "version": "1.0.0", - "description": "Demonstrates modular tool organization", - "total_tools": 6, # 4 imported + 2 defined here - } -``` - -However, if you need to define more than a few tools, this can make your MCP server file longer and harder to read and maintain. Instead, you can define your tools in separate files and import them. - -## Importing tools - -You can import tools from separate files like this: - -```python filename="server.py" -from tools.math_tools import add, multiply -from tools.text_tools import capitalize_string, word_count -``` - -You could also import specific tools from Arcade PyPI packages: - -```python filename="server.py" -# This is a prebuilt Arcade server - `pip install arcade-gmail` -from arcade_gmail.tools import list_emails -``` - -You can also import whole modules that contain tools like this: - -```python filename="server.py" -# This is a prebuilt Arcade server - `pip install arcade-reddit` -import arcade_reddit -``` - -Add imported tools explicitly to the `MCPApp` instance like this: - -```python filename="server.py" -app.add_tool(add) -app.add_tool(list_emails) -app.add_tools_from_module(arcade_reddit) -``` - -## Key takeaways - -- Keep your MCP server file clean and readable by defining tools in separate files -- Store your tools in a `tools` directory in your project alongside your MCP server file -- You can import tools from other Arcade packages and your own files -- Add imported tools explicitly to the MCP server app object - -## Example Code - - -```python filename="server.py" -#!/usr/bin/env python3 - -import sys -from typing import Annotated - -from arcade_mcp_server import MCPApp - -# Import tools from our mock 'tools' directory -# In a real project, these could come from actual separate files -from tools.math_tools import add, multiply -from tools.text_tools import capitalize_string, word_count - -# In a real project, you could import from Arcade PyPI packages - -# e.g. `pip install arcade-gmail` -# import arcade_gmail - -# Create the MCP application -app = MCPApp( - name="organized_server", - version="1.0.0", - instructions="Example server demonstrating modular tool organization", -) - -# Method 1: Add imported tools explicitly -app.add_tool(add) -app.add_tool(multiply) -app.add_tool(capitalize_string) -app.add_tool(word_count) -# app.add_tools_from_module(arcade_gmail) - - -# Method 2: Define tools directly on the app -@app.tool -def server_info() -> Annotated[dict, "Information about this server"]: - """Return information about this MCP server.""" - return { - "name": "Organized Server", - "version": "1.0.0", - "description": "Demonstrates modular tool organization", - "total_tools": 6, # 4 imported + 2 defined here - } - - -@app.tool -def combine_results( - text: Annotated[str, "Text to process"], - add_num: Annotated[int, "Number to add"], - multiply_num: Annotated[int, "Number to multiply"], -) -> Annotated[dict, "Combined results from multiple tools"]: - """Demonstrate using multiple tools together.""" - return { - "original_text": text, - "capitalized": capitalize_string(text), - "word_count": word_count(text), - "math_result": multiply(add(5, add_num), multiply_num), - } - - -if __name__ == "__main__": - # Check if stdio transport was requested - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - print(f"Starting {app.name} v{app.version}") - print(f"Transport: {transport}") - print("Setting up database...") - # simulate a database setup - print("Database setup complete") - - # Run the server - app.run(transport=transport, host="127.0.0.1", port=8000) -``` - -### Run your MCP server - - - - -```bash -uv run server.py -``` - - - - -```bash -uv run server.py http -``` - -For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). - - - - diff --git a/app/en/home/build-tools/providing-useful-tool-errors/page.mdx b/app/en/home/build-tools/providing-useful-tool-errors/page.mdx deleted file mode 100644 index ec5ba4672..000000000 --- a/app/en/home/build-tools/providing-useful-tool-errors/page.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Provide Useful Tool Errors" -description: "Learn how to provide good errors when building tools with Arcade MCP" ---- - -import { Tabs } from "nextra/components"; -import { ErrorHierarchy } from "@/app/_components/error-hierarchy"; - -# Providing useful tool errors - -When building tools with Arcade MCP, understanding error handling is crucial for creating robust and reliable tools. This guide covers everything you need to know about handling errors from a tool developer's perspective. - -## Error handling philosophy - -Arcade's error handling is designed to minimize boilerplate code while providing rich error information. In most cases, you don't need to explicitly handle errors in your tools because the `@tool` decorator automatically adapts common exceptions into appropriate Arcade errors. - - - -## Error adapters - -Error adapters automatically translate common exceptions (from `httpx`, `requests`, SDKs, etc.) into appropriate Arcade errors. This means zero boilerplate error handling code for you. To see which SDKs already have error adapters, see [arcade_tdk/error_adapters/__init__.py](https://github.com/ArcadeAI/arcade-ai/blob/main/libs/arcade-tdk/arcade_tdk/error_adapters/__init__.py). You may want to create your own error adapter or contribute an error adapter to the TDK. If so, see the [HTTP Error Adapter](https://github.com/ArcadeAI/arcade-ai/blob/main/libs/arcade-tdk/arcade_tdk/providers/http/error_adapter.py) for an example. Ensure your error adapter implements the [ErrorAdapter protocol](https://github.com/ArcadeAI/arcade-ai/blob/main/libs/arcade-tdk/arcade_tdk/error_adapters/base.py). - -### Automatic error adaptation - -For tools using `httpx` or `requests`, error adaptation happens automatically: - -```python -from typing import Annotated -from arcade_mcp_server import tool -import httpx - -@tool -def fetch_data( - url: Annotated[str, "The URL to fetch data from"], -) -> Annotated[dict, "The data fetched from the API endpoint"]: - """Fetch data from an API endpoint.""" - # No need to wrap in try/catch - Arcade handles HTTP errors automatically - response = httpx.get(url) - response.raise_for_status() # This will be adapted to UpstreamError if it raises - return response.json() -``` - -### Explicit error adapters - -For tools using specific SDKs, you can specify error adapters explicitly: - -```python -import googleapiclient -from typing import Annotated -from arcade_mcp_server import tool -from arcade_tdk.error_adapters import GoogleErrorAdapter - -@tool( - requires_auth=Google(scopes=["https://www.googleapis.com/auth/gmail.readonly"]), - error_adapters=[GoogleErrorAdapter] # note the tool opts-into the error adapter -) -def send_email( - num_emails: Annotated[int, "The number of emails to send"], -) -> Annotated[dict, "The emails sent using the Gmail API"]: - """Send an email using the Gmail API.""" - # Google API Client errors will be automatically adapted to Upstream Arcade errors for you - service = _build_gmail_service(context) - emails = service.users.messages().get( - userId="me", - id=num_emails - ).execute() # This will be adapted to UpstreamError if it raises - parsed_emails = _parse_emails(emails) - return parsed_emails -``` - -## When to raise errors explicitly - -While Arcade handles most errors automatically, there are specific cases where you should raise errors explicitly: - -### RetryableToolError - -Use when the LLM can retry the tool call with more context to improve the tool call's input parameters: - -```python -from typing import Annotated -from arcade_mcp_server import tool -from arcade_tdk.errors import RetryableToolError - -@tool(requires_auth=Reddit(scopes=["read"])) -def search_posts( - subreddit: Annotated[str, "The subreddit to search in"], - query: Annotated[str, "The query to search for"], -) -> Annotated[list[dict], "The posts found in the subreddit"]: - """Search for posts in a subreddit.""" - if is_invalid_subreddit(subreddit): - # additional_prompt_content should be provided back to the LLM - raise RetryableToolError( - "Please specify a subreddit name, such as 'python' or 'programming'", - additional_prompt_content=f"{subreddit} is an invalid subreddit name. Please specify a valid subreddit name" - ) - # ... rest of implementation -``` - -Learn more about [RetryableToolError](/home/build-tools/retry-tools-with-improved-prompt). - -### ContextRequiredToolError - -Use when additional context from the user or orchestrator is needed before the tool call can be retried by an LLM: - -```python -from os import path -from typing import Annotated -from arcade_mcp_server import tool -from arcade_tdk.errors import ContextRequiredToolError - -@tool -def delete_file(filename: Annotated[str, "The filename to delete"]) -> Annotated[str, "The filename that was deleted"]: - """Delete a file from the system.""" - if not os.path.exists(filename): - raise ContextRequiredToolError( - "File with provided filename does not exist", - additional_prompt_content=f"{filename} does not exist. Did you mean one of these: {get_valid_filenames()}", - ) - # ... deletion logic -``` - -### ToolExecutionError - -Use for unrecoverable, but known, errors when you want to provide specific error context: - -```python -from typing import Annotated -from arcade_mcp_server import tool -from arcade_tdk.errors import ToolExecutionError - -@tool -def process_data(data_id: Annotated[str, "The ID of the data to process"]) -> Annotated[dict, "The processed data"]: - """Process data by ID.""" - try: - data = get_data_from_database(data_id) - except Exception as e: - raise ToolExecutionError("Database connection failed.") from e - # ... processing logic -``` - -### UpstreamError - -Use for custom handling of upstream service errors: - -```python -from arcade_mcp_server import tool -from arcade_tdk.errors import UpstreamError -import httpx - -@tool -def create_issue(title: str, description: str) -> dict: - """Create a GitHub issue.""" - try: - response = httpx.post("/repos/owner/repo/issues", json={ - "title": title, - "body": description - }) - response.raise_for_status() - except httpx.HTTPStatusError as e: - if e.response.status_code == 422: - raise UpstreamError( - "Invalid issue data provided. Check title and description.", - status_code=422 - ) from e - # Let other HTTP errors be handled automatically - raise - - return response.json() -``` - -## Common error scenarios - -### Tool definition errors - -These errors occur when your tool has invalid definitions and are caught when the tool is loaded: - -#### Invalid input parameter types - -```python -from arcade_mcp_server import tool - -@tool -def invalid_tool(data: tuple[str, str, str]) -> str: # ❌ Tuples not supported - """This will raise a ToolInputSchemaError.""" - return f"Hello {data[0]}" -``` - -#### Missing return type annotation - -```python -from arcade_mcp_server import tool - -@tool -def invalid_tool(name: str): # ❌ Missing return type - """This will raise a ToolOutputSchemaError.""" - return f"Hello {name}" -``` - -#### Invalid parameter annotations - -```python -from typing import Annotated -from arcade_mcp_server import tool - -@tool -def invalid_tool(name: Annotated[str, "desc1", "desc2", "extra"]) -> str: # ❌ Too many annotations - """This will raise a ToolInputSchemaError.""" - return f"Hello {name}" -``` - -### Runtime errors - -These errors occur during tool execution: - -#### Output type mismatch - -```python -from typing import Annotated -from arcade_mcp_server import tool - -@tool -def invalid_output(name: Annotated[str, "Name to greet"]) -> str: - """Says hello to a friend.""" - return ["hello", name] # ❌ Returns list instead of string -``` - -This will raise a `ToolOutputError` because the return type doesn't match the annotation. - -## Handling tool errors in agents - -To learn more about how to handle tool errors in your Agent, see the [Use Tools](/home/use-tools/error-handling) section. diff --git a/app/en/home/build-tools/retry-tools-with-improved-prompt/page.mdx b/app/en/home/build-tools/retry-tools-with-improved-prompt/page.mdx deleted file mode 100644 index e6f0623ec..000000000 --- a/app/en/home/build-tools/retry-tools-with-improved-prompt/page.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Retry Tools with Improved Prompt" -description: "Documentation for retrying tools with improved prompts in the Arcade Tool SDK" ---- - -# RetryableToolError in Arcade - -Sometimes you may want to retry a tool call with additional context to improve the tool call's input parameters predicted by the model and try again. You can do this by raising a `RetryableToolError` within the tool. - -### Understanding RetryableToolError - -Raising the `RetryableToolError` is useful when you want to retry the tool call and give the model that is generating the tool call's input parameters additional context to improve the parameters for the next tool call. - -### When to Use RetryableToolError - -A RetryableToolError should be raised from within a tool if additional prompt content would likely improve the tool call outcome. - -### Example: Sending a Direct Message in Slack - -Below is an example of a tool that sends a direct message to a user in Slack: - -1. If the specified user is not found, the tool retrieves a list of all valid inputs for the `user_name` parameter. -2. The tool then raises a `RetryableToolError` with the list of valid inputs. -3. This allows the model to generate a valid input for the `user_name` parameter in the next tool call iteration. - -```python {44-49} -from typing import Annotated - -from slack_sdk import WebClient - -from arcade_core.errors import RetryableToolError -from arcade_mcp_server import Context, tool -from arcade_mcp_server.auth import Slack - - -@tool( - requires_auth=Slack( - scopes=[ - "chat:write", - "im:write", - "users.profile:read", - "users:read", - ], - ) -) -def send_dm_to_user( - context: Context, - user_name: Annotated[ - str, - "The Slack username of the person you want to message. Slack usernames are ALWAYS lowercase.", - ], - message: Annotated[str, "The message you want to send"], -) -> Annotated[str, "A confirmation message that the DM was sent"]: - """Send a direct message to a user in Slack.""" - - slackClient = WebClient(token=context.authorization.token) - - # Step 1: Retrieve the user's Slack ID based on their username - userListResponse = slackClient.users_list() - user_id = None - for user in userListResponse["members"]: - if user["name"].lower() == user_name.lower(): - user_id = user["id"] - break - - # If the user is not found, raise a RetryableToolError with a - # list of all valid inputs for the user_name parameter - if not user_id: - raise RetryableToolError( - "User not found", - developer_message=f"User with username '{user_name}' not found.", - additional_prompt_content=f"Valid values for user_name input param: {userListResponse}", - retry_after_ms=500, - ) - - # Step 2: Retrieve the DM channel ID with the user - im_response = slackClient.conversations_open(users=[user_id]) - dm_channel_id = im_response["channel"]["id"] - - # Step 3: Send the DM - slackClient.chat_postMessage(channel=dm_channel_id, text=message) - - return "DM sent successfully" -``` diff --git a/app/en/home/build-tools/tool-context/page.mdx b/app/en/home/build-tools/tool-context/page.mdx deleted file mode 100644 index 970768202..000000000 --- a/app/en/home/build-tools/tool-context/page.mdx +++ /dev/null @@ -1,296 +0,0 @@ ---- -title: "Context and MCP tools" -description: "What Arcade's Tool Context is and how to use it." ---- - -import { Callout, Tabs } from "nextra/components"; - -# Understanding `Context` and tools - -The `Context` class is used by tools for both runtime capabilities and tool-specific data access. Tools receive a populated `Context` instance as a parameter. Tools should not create `Context` instances directly. - - - - -Understand how to use the `Context` object to access runtime capabilities and tool-specific data. - - - - - -1. Tool-specific data that can be accessed using the `Context` object: - - Access OAuth token via `context.get_auth_token_or_empty` - - Access secrets via `context.get_secret` - - Access user_id via `context.user_id` -1. Runtime capabilities that can be accessed using the `Context` object: - - Log messages via `context.log` - - Request LLM sampling via `context.sampling` - - Request user elicitation via `context.ui.elicit` - - Report progress via `context.progress.report` - - - -## How `Context` Works - -When a tool that requires authorization is invoked, the MCP server automatically: - -1. Creates an instance of `Context` and populates it with the runtime capabilities and tool-specific data -2. Passes this object to your tool's first parameter named "context" - -You can then use the `Context` object to make requests to external APIs that require an OAuth token. - -Let's walk through an example (or skip to [the full code](#example-code)). - -## Context Features - -### Tool-Specific Data - -#### Tool secrets - -Specify required secrets using the `requires_secrets` argument of the `@tool` decorator and access them securely using the `get_secret` method: - -```python -@tool(requires_secrets=["DATABASE_URL", "API_KEY"]) -async def my_tool(context: Context) -> str: - try: - api_key = context.get_secret("API_KEY") - except ValueError: - # Handle missing secret - return "Do something interesting with the secret" -``` - -#### OAuth token - -Specify required authorization using the `requires_auth` argument of the `@tool` decorator and access the OAuth token securely using the `get_auth_token_or_empty` method: - -```python -@tool(requires_auth=ClickUp()) -async def my_tool(context: Context) -> str: - oauth_token = context.get_auth_token_or_empty() - - return "Do something interesting with the OAuth token" -``` - -#### User Info - -Access information about the user that authorized the tool using the `authorization.user_info` attribute. Note that this is only available if the tool's auth provider supports it (e.g., the LinkedIn auth provider provides the user ID): - -```python -user_info = context.authorization.user_info -``` - -### Runtime Capabilities - -#### Logging - -[Logging in MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging) provides a standardized channel for servers to emit structured, leveled messages to clients. Logging is useful for observability, debugging, and user feedback during tool execution. - -You can send log messages at different levels using the `log` attribute of the `Context` object like this: - -```python -await context.log.debug("Debug message") -await context.log.info("Information message") -await context.log.warning("Warning message") -await context.log.error("Error message") -await context.log.log("info", "Info message") # equivalent to await context.log.info("Info message") -``` - -#### Sampling - -[Sampling in MCP](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) is a way for servers to request LLM sampling (“completions” or “generations”) from language models via clients. This flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities—with no server API keys necessary. - -```python -await context.sampling.create_message(messages, system_prompt) -``` - -#### Elicitation - -[Elicitation in MCP](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) is a way for servers to request additional information from users through the client during interactions. This flow allows clients to maintain control over user interactions and data sharing while enabling servers to gather necessary information dynamically. - -```python -elicitation_schema = {"type": "object", "properties": {"nickname": {"type": "string"}}} - -await context.ui.elicit("What is your nickname?", elicitation_schema) -``` - -#### Progress Reporting - -[Progress reporting in MCP](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) is a way for servers to report progress for long-running operations to clients. - -```python -await context.progress.report(current, total, "Processing...") -``` - -## Example Code - -The following is an example that shows how tools can access runtime features through -`Context`, including logging, secrets, and progress reporting. - -### Environment Variables - -```env -API_KEY="your-secret-key" -DATABASE_URL="postgresql://localhost/mydb" -``` - - - -For the code to work, you must define your environment variables in a `.env` file at the same directory as your entrypoint file. - - - -```python filename="server.py" -#!/usr/bin/env python3 - -import sys -from typing import Annotated - -from arcade_mcp_server import Context, MCPApp - -# Create the MCP application -app = MCPApp( - name="context_example", - version="1.0.0", - instructions="Example server demonstrating Context usage", -) - - -@app.tool(requires_secrets=["API_KEY"]) -async def secure_api_call( - context: Context, - endpoint: Annotated[str, "API endpoint to call"], - method: Annotated[str, "HTTP method (GET, POST, etc.)"] = "GET", -) -> Annotated[str, "API response or error message"]: - """Make a secure API call using secrets from context.""" - - # Access secrets from environment via Context helper - try: - api_key = context.get_secret("API_KEY") - except ValueError: - await context.log.error("API_KEY not found in environment") - return "Error: API_KEY not configured" - - # Log the API call - await context.log.info(f"Making {method} request to {endpoint}") - - # Simulate API call (in real code, use httpx) - return f"Successfully called {endpoint} with API key: {api_key[:4]}..." - - -# Don't forget to add the secret to the .env file or export it as an environment variable -@app.tool(requires_secrets=["DATABASE_URL"]) -async def database_info( - context: Context, table_name: Annotated[str | None, "Specific table to check"] = None -) -> Annotated[str, "Database connection info"]: - """Get database connection information from context.""" - - # Get database URL from secrets - try: - db_url = context.get_secret("DATABASE_URL") - except ValueError: - db_url = "Not configured" - - if table_name: - return f"Database: {db_url}\nChecking table: {table_name}" - - return f"Database: {db_url}" - -@app.tool -async def logging_tool(context: Context, message: Annotated[str, "The message to log"]) -> str: - """Log a message at varying levels.""" - await context.log.log("debug", f"Debug via log.log: {message}") - await context.log.debug(f"Debug via log.debug: {message}") - await context.log.info(f"Info via log.info: {message}") - await context.log.warning(f"Warning via log.warning: {message}") - await context.log.error(f"Error via log.error: {message}") - - return "Logged!" - -@app.tool -async def reporting_progress(context: Context) -> str: - """Report progress back to the client""" - total = 5 - - for i in range(total): - await context.progress.report(i + 1, total=total, message=f"Step {i + 1} of {total}") - - return "All progress reported successfully" - -@app.tool -async def sampling( - context: Context, text: Annotated[str, "The text to be summarized by the client's model"] -) -> str: - """Summarize the text using the client's model.""" - result = await context.sampling.create_message( - messages=text, - system_prompt=( - "You are a helpful assistant that summarizes text. " - "Given a text, you should summarize it in a few sentences." - ), - ) - return result.text - -@app.tool -async def elicit_nickname(context: Context) -> str: - """Ask the end user for their nickname, and then use it to greet them.""" - elicitation_schema = {"type": "object", "properties": {"nickname": {"type": "string"}}} - result = await context.ui.elicit( - "What is your nickname?", - schema=elicitation_schema, - ) - - if result.action == "accept": - return f"Hello, {result.content['nickname']}!" - elif result.action == "decline": - return "User declined to provide a nickname." - elif result.action == "cancel": - return "User cancelled the elicitation." - - return "Unknown response from client" - - -if __name__ == "__main__": - # Check if stdio transport was requested - transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" - - # Run the server - app.run(transport=transport, host="127.0.0.1", port=8000) -``` - -### Run your MCP server - - - - -```bash -uv run server.py -``` - - - - -```bash -uv run server.py http -``` - -For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). - - - - - -## Key Concepts - -- **Context Parameter** Tools can receive a populated `Context` as their first parameter -- **Async Functions** Use `async def` for tools that use runtime context features -- **Secure Secrets** Secrets are accessed through context, not hardcoded -- **Structured Logging** Log at appropriate levels for debugging -- **Progress Updates** Keep users informed during long operations - -### Next Steps - -- [Build a custom tool that requires user authorization](/home/build-tools/create-a-tool-with-auth) -- [Build a custom tool with secrets](/home/build-tools/create-a-tool-with-secrets) diff --git a/app/en/home/compare-server-types/page.mdx b/app/en/home/compare-server-types/page.mdx deleted file mode 100644 index 3dfecf1ff..000000000 --- a/app/en/home/compare-server-types/page.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Compare Server Types" -description: "Compare the different types of MCP servers" ---- - -# Compare MCP Server Types - -Depending on the transport you use and where you want to run your MCP server, Arcade offers different functionalities and features. Below is a comparison of the different server types and their capabilities. - -| Transport | Deployment | Tools without requirements | Tools with secrets | Tools with auth (single-user) | Tools with auth (multi-user) | -| --------- | ----------------------------------------------------------------------- | :------------------------: | :----------------: | :---------------------------: | :--------------------------: | -| stdio | local | ✅ | ✅ | ✅ | ❌ | -| http | local ([unprotected](/home/glossary#unprotected-mcp-servers)) | ✅ | ❌ | ❌ | ❌ | -| http | remote ([unprotected](/home/glossary#unprotected-mcp-servers)) | ✅ | ❌ | ❌ | ❌ | -| http | local ([protected](/home/glossary#protected-mcp-servers)) `coming soon` | ✅ | ✅ | ✅ | ✅ | -| http | remote ([protected](/home/glossary#protected-mcp-servers)) | ✅ | ✅ | ✅ | ✅ | -| http | Arcade Cloud | ✅ | ✅ | ✅ | ✅ | diff --git a/app/en/home/configure-arcade-section/_meta.tsx b/app/en/home/configure-arcade-section/_meta.tsx new file mode 100644 index 000000000..152e60c03 --- /dev/null +++ b/app/en/home/configure-arcade-section/_meta.tsx @@ -0,0 +1,7 @@ +export default { + "overview-updated": "Overview", + "dashboard-section": "Dashboard", + "create-tenants-section": "Create Tenants", + "create-projects-section": "Create Projects", + "arcade-cli-section": "Using Arcade's CLI", +}; diff --git a/app/en/home/configure-arcade-section/arcade-cli-section/page.mdx b/app/en/home/configure-arcade-section/arcade-cli-section/page.mdx new file mode 100644 index 000000000..a5194561a --- /dev/null +++ b/app/en/home/configure-arcade-section/arcade-cli-section/page.mdx @@ -0,0 +1,7 @@ +# Using Arcade's CLI + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Arcade's CLI. \ No newline at end of file diff --git a/app/en/home/configure-arcade-section/create-projects-section/page.mdx b/app/en/home/configure-arcade-section/create-projects-section/page.mdx new file mode 100644 index 000000000..6cbf0f75d --- /dev/null +++ b/app/en/home/configure-arcade-section/create-projects-section/page.mdx @@ -0,0 +1,7 @@ +# Create Projects + +Documentation coming soon. + +## Overview + +This section will contain detailed information about creating projects. \ No newline at end of file diff --git a/app/en/home/configure-arcade-section/create-tenants-section/page.mdx b/app/en/home/configure-arcade-section/create-tenants-section/page.mdx new file mode 100644 index 000000000..b6ed20f6c --- /dev/null +++ b/app/en/home/configure-arcade-section/create-tenants-section/page.mdx @@ -0,0 +1,7 @@ +# Create Tenants + +Documentation coming soon. + +## Overview + +This section will contain detailed information about creating tenants. \ No newline at end of file diff --git a/app/en/home/configure-arcade-section/dashboard-section/page.mdx b/app/en/home/configure-arcade-section/dashboard-section/page.mdx new file mode 100644 index 000000000..a1c464252 --- /dev/null +++ b/app/en/home/configure-arcade-section/dashboard-section/page.mdx @@ -0,0 +1,7 @@ +# Dashboard + +Documentation coming soon. + +## Overview + +This section will contain detailed information about the Arcade dashboard. \ No newline at end of file diff --git a/app/en/home/configure-arcade-section/overview-updated/page.mdx b/app/en/home/configure-arcade-section/overview-updated/page.mdx new file mode 100644 index 000000000..3ab319f05 --- /dev/null +++ b/app/en/home/configure-arcade-section/overview-updated/page.mdx @@ -0,0 +1,7 @@ +# overview-updated + +Documentation coming soon. + +## Overview + +This section will contain detailed information about overview-updated. diff --git a/app/en/home/configure-arcade/page.mdx b/app/en/home/configure-arcade/page.mdx deleted file mode 100644 index f80033e6c..000000000 --- a/app/en/home/configure-arcade/page.mdx +++ /dev/null @@ -1,27 +0,0 @@ -# Configure Arcade - -This is a placeholder page for configuring Arcade. - -## Overview - -Learn how to set up and configure Arcade for your organization's needs. - -## Configuration Areas - -- Dashboard settings -- Tenant management -- Project configuration -- Security settings - -## Getting Started - -1. Access the Arcade Dashboard -2. Create your organization -3. Set up projects and tenants -4. Configure authentication - -## Advanced Configuration - -- Enterprise SSO -- Role-based access control -- Custom authentication providers \ No newline at end of file diff --git a/app/en/home/create-projects/page.mdx b/app/en/home/create-projects/page.mdx deleted file mode 100644 index d1f49a43c..000000000 --- a/app/en/home/create-projects/page.mdx +++ /dev/null @@ -1,27 +0,0 @@ -# Create Projects - -This is a placeholder page for creating projects in Arcade. - -## Overview - -Learn how to create and manage projects within your Arcade organization. - -## Project Structure - -Projects help organize your tools, configurations, and team access within Arcade. - -## Creating a Project - -1. Access the Arcade Dashboard -2. Navigate to Projects -3. Click "New Project" -4. Configure project settings -5. Invite team members - -## Project Settings - -- Project name and description -- Tool configurations -- Team permissions -- Environment variables -- API keys and secrets \ No newline at end of file diff --git a/app/en/home/create-tenants/page.mdx b/app/en/home/create-tenants/page.mdx deleted file mode 100644 index adedd4596..000000000 --- a/app/en/home/create-tenants/page.mdx +++ /dev/null @@ -1,26 +0,0 @@ -# Create Tenants - -This is a placeholder page for creating tenants in Arcade. - -## Overview - -Learn how to create and manage tenants for multi-user applications. - -## What are Tenants? - -Tenants allow you to isolate data and configurations for different organizations or user groups within your application. - -## Creating a Tenant - -1. Navigate to the Dashboard -2. Go to the Tenants section -3. Click "Create New Tenant" -4. Configure tenant settings -5. Set up authentication - -## Tenant Configuration - -- Tenant name and description -- Authentication settings -- Tool access permissions -- Usage limits and quotas \ No newline at end of file diff --git a/app/en/home/crewai/_meta.tsx b/app/en/home/crewai/_meta.tsx index 67edee61a..74c33d663 100644 --- a/app/en/home/crewai/_meta.tsx +++ b/app/en/home/crewai/_meta.tsx @@ -8,8 +8,11 @@ const meta: MetaRecord = { copyPage: true, }, }, - "use-arcade-tools": { - title: "Using Arcade tools", + "quickstart-python": { + title: "Quickstart (Python)", + }, + "quickstart-typescript": { + title: "Quickstart (Typescript)", }, "custom-auth-flow": { title: "Custom auth flow", diff --git a/app/en/home/crewai/quickstart-python/page.mdx b/app/en/home/crewai/quickstart-python/page.mdx new file mode 100644 index 000000000..4b5421156 --- /dev/null +++ b/app/en/home/crewai/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using CrewAI with Python. \ No newline at end of file diff --git a/app/en/home/crewai/quickstart-typescript/page.mdx b/app/en/home/crewai/quickstart-typescript/page.mdx new file mode 100644 index 000000000..92c76c387 --- /dev/null +++ b/app/en/home/crewai/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using CrewAI with TypeScript. \ No newline at end of file diff --git a/app/en/home/crewai/use-arcade-tools/page.mdx b/app/en/home/crewai/use-arcade-tools/page.mdx deleted file mode 100644 index 555dc8e87..000000000 --- a/app/en/home/crewai/use-arcade-tools/page.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: "Use Arcade tools with CrewAI" -description: "Integrate Arcade tools into your CrewAI applications" ---- - -import { Steps } from "nextra/components"; -import ToggleContent from "@/app/_components/toggle-content"; - -## Use CrewAI with Arcade - -In this guide, we will explore how to integrate Arcade tools into your CrewAI application. Follow the step-by-step instructions below. If a tool requires authorization, an authorization URL will appear in the console, waiting for your approval. This process ensures that only the tools you choose to authorize are executed. - -To tailor the tool authorization flow to meet your application's specific needs, check out the [Custom Auth Flow with CrewAI](/home/crewai/custom-auth-flow) guide. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Set up your environment - -Install the required package, and ensure your environment variables are set with your Arcade and OpenAI API keys: - -```bash -pip install crewai-arcade -``` - -### Configure API keys - -Provide your Arcade and OpenAI API keys. You can store them in environment variables like so: - -```bash -export ARCADE_API_KEY="your_arcade_api_key" -export OPENAI_API_KEY="your_openai_api_key" -``` - -### Get Arcade tools - -Use the `ArcadeToolManager` to initialize, add, and get Arcade tools: - -```python -from crewai_arcade import ArcadeToolManager - -manager = ArcadeToolManager(default_user_id="{arcade_user_id}") - -""" -Retrieves the provided tools and/or MCP Servers as CrewAI StructuredTools. -""" -tools = manager.get_tools(tools=["Gmail.ListEmails"], toolkits=["Slack"]) -``` - -### Use tools in your CrewAI agent team - -Create a Crew that uses your tools. When the tool is called, you will be prompted to go visit an authorization page to authorize the tool before it executes. - -```python -from crewai import Agent, Crew, Task -from crewai.llm import LLM - -crew_agent = Agent( - role="Main Agent", - backstory="You are a helpful assistant", - goal="Help the user with their requests", - tools=tools, - allow_delegation=False, - verbose=True, - llm=LLM(model="gpt-4o"), -) - -task = Task( - description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", - expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", - agent=crew_agent, - tools=crew_agent.tools, -) - -crew = Crew( - agents=[crew_agent], - tasks=[task], - verbose=True, - memory=True, -) - -result = crew.kickoff() - -print("\n\n\n ------------ Result ------------ \n\n\n") -print(result) -``` - - - - - -```python -from crewai import Agent, Crew, Task -from crewai.llm import LLM -from crewai_arcade import ArcadeToolManager - -manager = ArcadeToolManager(default_user_id="{arcade_user_id}") - -tools = manager.get_tools(tools=["Gmail.ListEmails"]) - - -crew_agent = Agent( - role="Main Agent", - backstory="You are a helpful assistant", - goal="Help the user with their requests", - tools=tools, - allow_delegation=False, - verbose=True, - llm=LLM(model="gpt-4o"), -) - -task = Task( - description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", - expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", - agent=crew_agent, - tools=crew_agent.tools, -) - -crew = Crew( - agents=[crew_agent], - tasks=[task], - verbose=True, - memory=True, -) - -result = crew.kickoff() - -print("\n\n\n ------------ Result ------------ \n\n\n") -print(result) -``` - - - -## Tips for selecting tools - -- **Relevance**: Pick only the tools you need. Avoid using all tools at once. -- **Avoid conflicts**: Be mindful of duplicate or overlapping functionality. - -## Next steps - -Now that you have integrated Arcade tools into your CrewAI agent team, you can: - -- Experiment with different toolkits, such as "Math" or "Search." -- Customize the agent's prompts for specific tasks. -- Customize the tool authorization and execution flow to meet your application's requirements. diff --git a/app/en/home/custom-apps/_meta.tsx b/app/en/home/custom-apps/_meta.tsx new file mode 100644 index 000000000..b56fb9e54 --- /dev/null +++ b/app/en/home/custom-apps/_meta.tsx @@ -0,0 +1,8 @@ +export default { + "calling-tools-custom-apps-2": "Calling tools in your custom apps", + "authorized-tool-calling": "Authorized Tool Calling", + "auth-status-check": "Checking Authorization Status", + "tool-formats": "Tool formats", + "connect-arcade-llm": "Connecting Arcade tools to your LLM", + "test-tool-performance": "Testing tool performance", +}; diff --git a/app/en/home/custom-apps/auth-status-check/page.mdx b/app/en/home/custom-apps/auth-status-check/page.mdx new file mode 100644 index 000000000..110951ac4 --- /dev/null +++ b/app/en/home/custom-apps/auth-status-check/page.mdx @@ -0,0 +1,7 @@ +# auth-status-check + +Documentation coming soon. + +## Overview + +This section will contain detailed information about auth-status-check. diff --git a/app/en/home/custom-apps/authorized-tool-calling/page.mdx b/app/en/home/custom-apps/authorized-tool-calling/page.mdx new file mode 100644 index 000000000..155ffc4a3 --- /dev/null +++ b/app/en/home/custom-apps/authorized-tool-calling/page.mdx @@ -0,0 +1,7 @@ +# authorized-tool-calling + +Documentation coming soon. + +## Overview + +This section will contain detailed information about authorized-tool-calling. diff --git a/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx b/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx new file mode 100644 index 000000000..916ded6a0 --- /dev/null +++ b/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx @@ -0,0 +1,7 @@ +# calling-tools-custom-apps-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about calling-tools-custom-apps-2. diff --git a/app/en/home/custom-apps/connect-arcade-llm/page.mdx b/app/en/home/custom-apps/connect-arcade-llm/page.mdx new file mode 100644 index 000000000..49a1760ef --- /dev/null +++ b/app/en/home/custom-apps/connect-arcade-llm/page.mdx @@ -0,0 +1,7 @@ +# connect-arcade-llm + +Documentation coming soon. + +## Overview + +This section will contain detailed information about connect-arcade-llm. diff --git a/app/en/home/custom-apps/test-tool-performance/page.mdx b/app/en/home/custom-apps/test-tool-performance/page.mdx new file mode 100644 index 000000000..160b83045 --- /dev/null +++ b/app/en/home/custom-apps/test-tool-performance/page.mdx @@ -0,0 +1,7 @@ +# test-tool-performance + +Documentation coming soon. + +## Overview + +This section will contain detailed information about test-tool-performance. diff --git a/app/en/home/custom-apps/tool-formats/page.mdx b/app/en/home/custom-apps/tool-formats/page.mdx new file mode 100644 index 000000000..b8dae2704 --- /dev/null +++ b/app/en/home/custom-apps/tool-formats/page.mdx @@ -0,0 +1,7 @@ +# tool-formats + +Documentation coming soon. + +## Overview + +This section will contain detailed information about tool-formats. diff --git a/app/en/home/custom-mcp-server-quickstart/page.mdx b/app/en/home/custom-mcp-server-quickstart/page.mdx deleted file mode 100644 index e4701d707..000000000 --- a/app/en/home/custom-mcp-server-quickstart/page.mdx +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: "Build MCP Server QuickStart" -description: "Create your custom MCP Server with Arcade MCP" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; -import { SignupLink } from "@/app/_components/analytics"; -import { GuideOverview } from "@/app/_components/guide-overview"; - -# Build MCP Server QuickStart - - - - -Build and run an MCP Server with tools that you create. - - - - - -- Python 3.10 or higher -- The [`uv` package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- Install `arcade-mcp`, the secure framework for building MCP servers -- Start your MCP server and connect to it from your favorite MCP client -- Call a simple tool -- Call a tool that requires a secret -- Create an Arcade account -- Call a tool that requires auth - - - - - - -## Install the Arcade CLI - -In your terminal, run the following command to install the `arcade-mcp` package - Arcade's CLI: - - - - -```bash -uv tool install arcade-mcp -``` - -{" "} - - - This will install the Arcade CLI as a [uv - tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it - available system wide. - - - - - - -```bash -pip install arcade-mcp -``` - - - - -## Create Your Server - -In your terminal, run the following command to scaffold a new MCP Server called `my_server`: - -```bash -arcade new my_server -cd my_server/src/my_server -``` - -This generates a Python module with the following structure: - -```bash -my_server/ -├── src/ -│ └── my_server/ -│ ├── __init__.py -│ ├── .env.example -│ └── server.py -└── pyproject.toml -``` - -- **server.py** Entrypoint file with MCPApp and example tools -- **pyproject.toml** Dependencies and project configuration -- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py` - -`server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools: - -- **`greet`**: This tool has a single argument, the name of the person to greet. It requires no secrets or auth -- **`whisper_secret`**: This tool requires no arguments, and will output the last 4 characters of a `MY_SECRET_KEY` secret that you can define in your `.env` file. -- **`get_posts_in_subreddit`**: This tool has a single argument, a subreddit, and will return the latest posts on that subreddit, it requires the user to authorize the tool to perform a read operation on their behalf. - -> If you're having issues with the `arcade` command, please see the [Troubleshooting](#troubleshooting) section. - -## Setup the secrets in your environment - -Secrets are sensitive strings like passwords, API keys, or other tokens that grant access to a protected resource or API. Arcade includes the "whisper_secret" tool that requires a secret key to be set in your environment. If the secret is not set, the tool will return an error. - - - -You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret: - -```env filename=".env" -MY_SECRET_KEY="my-secret-value" -``` - -The generated project includes a `.env.example` file with the secret key name and example value. -You can rename it to `.env` to start using it. - -```bash -mv .env.example .env -``` - - - -You can set the environment variable in your terminal directly with this command: - -```bash -export MY_SECRET_KEY="my-secret-value" -``` - - - - -## Connect to Arcade to unlock authorized tool calling - -Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run: - -```bash -arcade login -``` - -Follow the instructions in your browser, and once you've finished, your terminal will be connected to your Arcade account. - -## Run your MCP Server - -Run your MCP Server using one of the following commands in your terminal: - - - - - -```bash -uv run server.py stdio -``` - - - When using the stdio transport, MCP clients typically launch the MCP server as - a subprocess. Because of this, the server may run in a different environment - and not have access to secrets defined in your local `.env` file. Please refer - to the [create a tool with - secrets](/home/build-tools/create-a-tool-with-secrets) guide for more - information. - - - - - -```bash -uv run server.py http -``` - -For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). - - - For security reasons, Local HTTP servers do not currently support tool-level - authorization and secrets. If you need to use tool-level authorization or - secrets locally, you should use the stdio transport and configure the Arcade - API key and secrets in your MCP connection settings. Otherwise, if you intend - to expose your HTTP MCP server to the public internet with tool-level - authorization and secrets, please follow the [deploying to the cloud with - Arcade Deploy](/home/serve-tools/arcade-deploy) guide or the [on-prem MCP - server](/home/deployment/on-prem-mcp) guide for secure remote deployment. - - - - - -You should see output like this in your terminal: - -```bash -2025-11-03 13:46:11.041 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet -2025-11-03 13:46:11.042 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret -2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit -INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools -``` - -## Configure your MCP Client(s) - -Now you can connect MCP Clients to your MCP server: - - - - - ```bash - # Configure Cursor to use your MCP server with the default transport (stdio) - arcade configure cursor - - # Configure Cursor to use your MCP server with the http transport - arcade configure cursor --transport http - ``` - - - - - ```bash - # Configure VS Code to use your MCP server with the default transport (stdio) - arcade configure vscode - - # Configure VS Code to use your MCP server with the http transport - arcade configure vscode --transport http - ``` - - - - - ```bash - # Configure Claude Desktop to use your MCP server with the default transport (stdio) - arcade configure claude - - # Configure Claude Desktop to use your MCP server with the http transport - arcade configure claude --transport http - ``` - - - - -## Try it out! - -Try calling your tool inside your assistant. - -Here's some prompts you can try: - -- "Get some posts from the r/mcp subreddit" -- "What's the last 4 characters of my secret key?" -- "Greet me as Supreme MCP Master" - - - -## Troubleshooting - -### `arcade` command not found or not working - -If you're getting issues with the `arcade` command, please make sure you did not install it outside of your virtual environment. For example, if your system-wide Python installation older than 3.10, you may need to uninstall arcade from that Python installation in order for the terminal to recognize the `arcade` command installed in your virtual environment. - -### The Reddit tool is not working - -Ensure you run `arcade login` and follow the instructions in your browser to connect to your Arcade account. - -### The Whisper Secret tool is not working - -Ensure you have set the environment variable in your terminal or `.env` file, and that it matches the secret key defined in the `@app.tool` decorator. If you are using the stdio transport, then ensure the environment variable is set in the MCP client's configuration file. - -## Next Steps - -- **Learn how to write a tool with auth**: [Create a tool with auth](/home/build-tools/create-a-tool-with-auth) -- **Learn how to write a tool with secrets**: [Create a tool with secrets](/home/build-tools/create-a-tool-with-secrets) -- **Learn more about the Context object**: [Tools and Context](/home/build-tools/tool-context) -- **Learn how to write tool evaluations**: [Create an evaluation suite](/home/evaluate-tools/create-an-evaluation-suite) to optimize them for LLM usage -- **Learn how to deploy your MCP server**: [Deploy your MCP server](/home/serve-tools/arcade-deploy) diff --git a/app/en/home/dashboard/page.mdx b/app/en/home/dashboard/page.mdx deleted file mode 100644 index 2d149b9b6..000000000 --- a/app/en/home/dashboard/page.mdx +++ /dev/null @@ -1,28 +0,0 @@ -# Dashboard - -This is a placeholder page for the Arcade Dashboard overview. - -## Overview - -Overview of various Dashboard tabs and jobs to be done. - -## Dashboard Sections - -### Projects Tab -Manage your Arcade projects and their configurations. - -### Tools Tab -Browse and manage your available tools and toolkits. - -### Analytics Tab -Monitor usage, performance, and tool calling metrics. - -### Settings Tab -Configure organization settings, authentication, and integrations. - -## Getting Started - -1. Log into the Arcade Dashboard -2. Create your first project -3. Configure your tools -4. Monitor usage and performance \ No newline at end of file diff --git a/app/en/home/deployment/_meta.tsx b/app/en/home/deployment/_meta.tsx deleted file mode 100644 index 33ad997c1..000000000 --- a/app/en/home/deployment/_meta.tsx +++ /dev/null @@ -1,22 +0,0 @@ -import type { MetaRecord } from "nextra"; - -const meta: MetaRecord = { - "*": { - theme: { - breadcrumb: true, - toc: true, - copyPage: true, - }, - }, - "arcade-cloud-infra": { - title: "Arcade Cloud Infrastructure", - }, - "on-prem-mcp": { - title: "On-premises MCP servers", - }, - "engine-configuration": { - title: "Engine configuration", - }, -}; - -export default meta; diff --git a/app/en/home/deployment/arcade-cloud-infra/page.mdx b/app/en/home/deployment/arcade-cloud-infra/page.mdx deleted file mode 100644 index cce088b45..000000000 --- a/app/en/home/deployment/arcade-cloud-infra/page.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Arcade Cloud Infrastructure" -description: "Learn about the infrastructure that powers Arcade Cloud" ---- - -# Arcade Cloud Infrastructure - -This page covers the infrastructure that powers Arcade Cloud, and what you might need to know about it. - -## Egress IP Addresses - -Traffic from Arcade Cloud will be existing our infrastructure from the following IP addresses: - -```sh -# Control Plane (Located in the USA) -3.140.92.118 -3.13.58.74 -3.149.34.246 - -# MCP Server Cluster 1 (Located in the USA) -3.150.210.23 -3.135.113.210 -3.131.234.5 -``` - -## VPC Peering - -VPC Peering is available for our enterprise customers upon request. If you are interested in VPC Peering, please [contact us](/home/contact-us). diff --git a/app/en/home/deployment/engine-configuration/page.mdx b/app/en/home/deployment/engine-configuration/page.mdx deleted file mode 100644 index 5ec5e8445..000000000 --- a/app/en/home/deployment/engine-configuration/page.mdx +++ /dev/null @@ -1,689 +0,0 @@ ---- -title: "Engine Configuration Templates" -description: "Arcade Engine Configuration Templates" ---- - -import { Callout, Tabs } from "nextra/components"; -import TableOfContents from "@/app/_components/table-of-contents"; - -# Engine Configuration - - - This page is for enterprise customers who are self-hosting the Arcade Engine. This is page contains advanced configuration options that are not applicable for most customers. - - -## Getting the Engine - - - - ```bash - brew install ArcadeAI/tap/arcade-engine - ``` - - Run it with: `arcade-engine` - -Troubleshooting: - -```bash -❌ Engine binary not found -``` - -or - -```bash -command not found: arcade-engine -``` - -This means that the Arcade Engine cannot be found in your path. Brew and Apt will automatically add the binary to your path. - -Check that the binary has been properly installed. These are the common installation locations): - -**Brew** - -```bash -ls $HOMEBREW_REPOSITORY/Cellar/arcade-engine//bin/arcade-engine -``` - -**Apt** - -```bash -ls /usr/bin/arcade-engine -``` - -If the binary is found, add it to your path with: - -```bash -export PATH=$PATH:/path/to/your/binary -``` - - - ```bash - wget -qO - https://deb.arcade.dev/public-key.asc | sudo apt-key add - - echo "deb https://deb.arcade.dev/ubuntu stable main" | sudo tee /etc/apt/sources.list.d/arcade-ai.list - sudo apt update - sudo apt install arcade-engine - ``` - - - The docker image for the engine can be pulled with - - ```bash - docker pull ghcr.io/arcadeai/engine:latest - ``` - - The engine can be run with: - - ```bash - docker run -d -p 9099:9099 -v ./engine.yaml:/bin/engine.yaml ghcr.io/arcadeai/engine:latest - ``` - - where config.yaml is the path to the [configuration file](/home/deployment/engine-configuration). - - - -Arcade uses configuration files to manage engine settings and default values. When you install the Arcade Engine, two files are created: -- The `engine.yaml` file for engine configuration. -- The `engine.env` file for environment variables. -Let's explore each file to understand their purpose and how to locate them. - -## Engine configuration file - -The `engine.yaml` file controls Arcade Engine settings. It supports variable expansion so you can integrate secrets and environment values seamlessly. You can customize this file to suit your setup. For more details, check the [Engine Configuration](/home/deployment/engine-configuration) page. - -Choose your installation method to view the default location of `engine.yaml`: - - - - ```bash - $HOMEBREW_REPOSITORY/etc/arcade-engine/engine.yaml - ``` - - - ```bash - /etc/arcade-ai/engine.yaml - ``` - - - ```bash - $HOME/.arcade/engine.yaml - ``` - To manually download the engine.yaml, you can get an example from the [Configuration Templates](/home/deployment/engine-configuration#engineyaml) and add it to `$HOME/.arcade/engine.yaml`. - - - -## Engine environment file - -The `engine.env` file contains default environment variables that power Arcade Engine. You can override these defaults by exporting your own variables or by editing the file directly. - -Select your installation method below to see the default path for `engine.env`: - - - - ```bash - $HOMEBREW_REPOSITORY/etc/arcade-engine/engine.env - ``` - - - ```bash - /etc/arcade-ai/engine.env - ``` - - - ```bash - $HOME/.arcade/engine.env - ``` - To manually download the `engine.env`, refer to the [Configuration Templates](/home/deployment/engine-configuration#engineenv). - - - - -Arcade Engine's configuration is a [YAML file](https://yaml.org/) with the following sections: - - - -## Specify a config file - -To start the Arcade Engine, pass a config file with `-c` or `--config`: - -```bash -arcade-engine -c /path/to/config.yaml -``` - -## Dotenv files - -Arcade Engine automatically loads environment variables from `.env` files in the directory where it was called. Use the `-e` or`--env` flag to specify a path: - -```bash -arcade-engine -e .env.dev -c config.yaml -``` - -## Secrets - -Arcade Engine supports two ways of passing sensitive information like API keys without storing them directly in the config file. - -Environment variables: - -```yaml {5} -topic: - area: - - id: primary - vendor: - api_key: ${env:OPENAI_API_KEY} -``` - -External files (useful in cloud setups): - -```yaml {5} -topic: - area: - - id: primary - vendor: - api_key: ${file:/path/to/secret} -``` - -## API configuration - -HTTP is the supported protocol for Arcade Engine's API. The following configuration options are available: - -- `api.development` _(optional, default: `false`)_ - Enable development mode, with more logging. -- `api.host` _(default: `localhost`)_ - Address to which Arcade Engine binds its server (e.g., `localhost` or `0.0.0.0`) -- `api.port` _(default: `9099`)_ - Port to which Arcade Engine binds its server (e.g., `9099` or `8080`) -- `api.public_host` _(optional)_ - External hostname of the API (e.g., `my-public-host.com`), if it differs from `api.host` (for example, when Arcade Engine is behind a reverse proxy) -- `api.read_timeout` _(optional, default: `30s`)_ - Timeout for reading data from clients -- `api.write_timeout` _(optional, default: `1m`)_ - Timeout for writing data to clients -- `api.idle_timeout` _(optional, default: `30s`)_ - Timeout for idle connections -- `api.max_request_body_size` _(optional, default: `4Mb`)_ - Maximum request body size - -A typical configuration for production looks like: - -```yaml -api: - development: false - host: localhost - port: 9099 -``` - -When the Arcade Engine is hosted in a container or behind a reverse proxy, set `api.public_host` to the external hostname of the API: - -```yaml -api: - development: false - host: localhost - port: 9099 - public_host: my-public-host.com -``` - -For local development, set `api.development = true`. - -## Auth configuration - -Arcade Engine manages auth for [AI tools](/home/auth/auth-tool-calling) and [direct API calls](/home/auth/call-third-party-apis-directly). It supports many built-in [auth providers](/home/auth-providers), and can also connect to any [OAuth 2.0](/home/auth-providers/oauth2) authorization server. - -The `auth.providers` section defines the providers that users can authorize with. Each provider must have a unique `id` in the array. There are two ways to configure a provider: - -For [built-in providers](/home/auth-providers), use the `provider_id` field to reference the pre-built configuration. For example: - -```yaml -auth: - providers: - - id: default-github - description: The default GitHub provider - enabled: true - type: oauth2 - provider_id: github - client_id: ${env:GITHUB_CLIENT_ID} - client_secret: ${env:GITHUB_CLIENT_SECRET} -``` - -For custom OAuth 2.0 providers, specify the full connection details in the `oauth2` sub-section. For full documentation on the custom provider configuration, see the [OAuth 2.0 provider configuration](/home/auth-providers/oauth2) page. - -You can specify a mix of built-in and custom providers. - -## Cache configuration - -The `cache` section configures the short-lived cache. - - - Configuring the cache is optional. If not configured, the cache will default - to an in-memory cache implementation suitable for a single-node Arcade Engine - deployment. - - -The `cache` section has the following configuration options: - -- `api_key_ttl` _(optional, default: `10s`)_ - The time-to-live for API keys in the cache - -Two cache implementations are available: - -- `in_memory` - _(default)_ An in-memory cache implementation suitable for a single-node Arcade Engine deployment. -- `redis` - A Redis cache implementation suitable for a multi-node Arcade Engine deployment: - -```yaml -cache: - api_key_ttl: 10s - redis: - addr: "localhost:6379" - password: "" - db: 0 -``` - -## Security configuration - -The `security` section configures the root encryption keys that the Arcade Engine uses to encrypt and decrypt data at rest. See the [storage configuration](#storage-configuration) section below to configure where data is stored. - -A typical configuration looks like this: - -```yaml -security: - root_keys: - - id: key1 - default: true - value: ${env:ROOT_KEY_1} - - id: key2 - value: ${env:ROOT_KEY_2} -``` - -Keys should be a long random string of characters. For example: - -```bash -openssl rand -base64 32 -``` - -### Default root key - -When you [install Arcade Engine locally](/home/deployment/engine-configuration), an `engine.env` file is created with a default root key: - -```bash -# Encryption keys (change this when deploying to production) -ROOT_KEY_1=default-key-value -``` - -This default value can only be used in development mode (see [API configuration](#api-configuration) above). - - - You **must** replace the value of `ROOT_KEY_1` in `engine.env` before - deploying to production. - - -## Storage configuration - -The `storage` section configures the storage backend that the Arcade Engine uses to store persistent data. - -There are three storage implementations available: - -- `in_memory` - _(default)_ An in-memory database, suitable for testing. -- `sqlite` - A SQLite file on disk, suitable for local development: - -```yaml -storage: - sqlite: - # Stores DB in ~/.arcade/arcade-engine.sqlite3 - connection_string: "@ARCADE_HOME/arcade-engine.sqlite3" -``` - -- `postgres` - A PostgreSQL database, suitable for production: - -```yaml -storage: - postgres: - user: ${env:POSTGRES_USER} - password: ${env:POSTGRES_PASSWORD} - host: ${env:POSTGRES_HOST} - port: ${env:POSTGRES_PORT} - db: ${env:POSTGRES_DB} - sslmode: require -``` - -## Telemetry configuration - -Arcade supports logs, metrics, and traces with [OpenTelemetry](https://opentelemetry.io/). - -If you are using the Arcade Engine locally, you can set the `environment` field to `local`. This will only output logs to the console: - -```yaml -telemetry: - environment: local - logging: - # debug, info, warn, error, fatal - level: debug - encoding: console -``` - -To connect to OpenTelemetry compatible collectors, set the necessary [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) in the `engine.env` file. -`environment` and `version` are fields that are added to the telemetry attributes, which can be filtered on later. - -```yaml -telemetry: - environment: prod - logging: - level: info - encoding: console -``` - -### Notes - -- The Engine service name is set to `arcade_engine` -- Traces currently cover the `/v1/health` endpoints, as well as authentication attempts - -## Tools configuration - -Arcade Engine orchestrates [tools](/home/use-tools/tools-overview) that AI models can use. - -The `tools.directors` section configures the mcp servers that are available to service tool calls: - -```yaml -tools: - directors: - - id: default - enabled: true - max_tools: 64 - workers: - - id: local_worker - enabled: true - http: - uri: "http://localhost:8002" - timeout: 30 - retry: 3 - secret: ${env:ARCADE_WORKER_SECRET} -``` - -When an MCP server is added to an enabled director, all of the tools hosted by that MCP server will be available to the model and through the Arcade API. - -### HTTP MCP Server configuration - -The `http` sub-section configures the HTTP client used to call the MCP Server's tools: - -- `uri` _(required)_ - The base URL of the MCP Server's tools -- `secret` _(required)_ - Secret used to authenticate with the MCP Server -- `timeout` _(optional, default: `30s`)_ - Timeout for calling the MCP Server's tools -- `retry` _(optional, default: `3`)_ - Number of times to retry a failed tool call - - - MCP Servers must be configured with a `secret` that is used to authenticate with - the MCP Server. This ensures that MCP Servers are not exposed to the public internet - without security. - -If `api.development = true`, the secret will default to `"dev"` for local development **only**. In production, the secret must be set to a random value. - - - -## Config file version history - -- 1.0: [Full example](https://raw.githubusercontent.com/ArcadeAI/docs/refs/heads/main/examples/code/home/configuration/engine/full_config.1.0.yaml) and [schema](https://raw.githubusercontent.com/ArcadeAI/schemas/refs/heads/main/engine/config/1.0/schema.json) - - -## Engine Config Templates - -### engine.yaml - -```yaml -# yaml-language-server: $schema=https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json -$schema: https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json - -api: - development: ${env:API_DEVELOPMENT} - host: ${env:ARCADE_API_HOST} - port: ${env:ARCADE_API_PORT} - # Optionally set public_host, in case the Arcade Engine is hosted in a container or behind a reverse proxy - #public_host: ${env:ARCADE_API_PUBLIC_HOST} - -auth: - providers: - - id: default-atlassian - description: "The default Atlassian provider" - enabled: false - type: oauth2 - provider_id: atlassian - client_id: ${env:ATLASSIAN_CLIENT_ID} - client_secret: ${env:ATLASSIAN_CLIENT_SECRET} - - - id: default-discord - description: "The default Discord provider" - enabled: false - type: oauth2 - provider_id: discord - client_id: ${env:DISCORD_CLIENT_ID} - client_secret: ${env:DISCORD_CLIENT_SECRET} - - - id: default-dropbox - description: "The default Dropbox provider" - enabled: false - type: oauth2 - provider_id: dropbox - client_id: ${env:DROPBOX_CLIENT_ID} - client_secret: ${env:DROPBOX_CLIENT_SECRET} - - - id: default-github - description: "The default GitHub provider" - enabled: false - type: oauth2 - provider_id: github - client_id: ${env:GITHUB_CLIENT_ID} - client_secret: ${env:GITHUB_CLIENT_SECRET} - - - id: default-google - description: "The default Google provider" - enabled: false - type: oauth2 - provider_id: google - client_id: ${env:GOOGLE_CLIENT_ID} - client_secret: ${env:GOOGLE_CLIENT_SECRET} - - - id: default-linkedin - description: "The default LinkedIn provider" - enabled: false - type: oauth2 - provider_id: linkedin - client_id: ${env:LINKEDIN_CLIENT_ID} - client_secret: ${env:LINKEDIN_CLIENT_SECRET} - - - id: default-microsoft - description: "The default Microsoft provider" - enabled: false - type: oauth2 - provider_id: microsoft - client_id: ${env:MICROSOFT_CLIENT_ID} - client_secret: ${env:MICROSOFT_CLIENT_SECRET} - - - id: default-reddit - description: "The default Reddit provider" - enabled: false - type: oauth2 - provider_id: reddit - client_id: ${env:REDDIT_CLIENT_ID} - client_secret: ${env:REDDIT_CLIENT_SECRET} - - - id: default-slack - description: "The default Slack provider" - enabled: false - type: oauth2 - provider_id: slack - client_id: ${env:SLACK_CLIENT_ID} - client_secret: ${env:SLACK_CLIENT_SECRET} - - - id: default-spotify - description: "The default Spotify provider" - enabled: false - type: oauth2 - provider_id: spotify - client_id: ${env:SPOTIFY_CLIENT_ID} - client_secret: ${env:SPOTIFY_CLIENT_SECRET} - - - id: default-twitch - description: "The default Twitch provider" - enabled: false - type: oauth2 - provider_id: twitch - client_id: ${env:TWITCH_CLIENT_ID} - client_secret: ${env:TWITCH_CLIENT_SECRET} - - - id: default-x - description: "The default X provider" - enabled: false - type: oauth2 - provider_id: x - client_id: ${env:X_CLIENT_ID} - client_secret: ${env:X_CLIENT_SECRET} - - - id: default-zoom - description: "The default Zoom provider" - enabled: false - type: oauth2 - provider_id: zoom - client_id: ${env:ZOOM_CLIENT_ID} - client_secret: ${env:ZOOM_CLIENT_SECRET} - -llm: - models: - - id: my-openai-model-provider - openai: - api_key: ${env:OPENAI_API_KEY} - #- id: my-anthropic-model-provider - # anthropic: - # api_key: ${env:ANTHROPIC_API_KEY} - # - id: my-ollama-model-provider - # openai: - # base_url: http://localhost:11434 - # chat_endpoint: /v1/chat/completions - # model: llama3.2 - # api_key: ollama - #- id: my-groq-model-provider - # openai: - # base_url: 'https://api.groq.com/openai/v1' - # api_key: ${env:GROQ_API_KEY} - -security: - root_keys: - - id: key1 - default: true - value: ${env:ROOT_KEY_1} - -storage: - postgres: - user: ${env:POSTGRES_USER} - password: ${env:POSTGRES_PASSWORD} - host: ${env:POSTGRES_HOST} - port: ${env:POSTGRES_PORT} - db: ${env:POSTGRES_DB} - sslmode: require - -telemetry: - environment: ${env:TELEMETRY_ENVIRONMENT} - logging: - # debug, info, warn, error - level: ${env:TELEMETRY_LOGGING_LEVEL} - encoding: ${env:TELEMETRY_LOGGING_ENCODING} - -tools: - directors: - - id: default - enabled: true - max_tools: 64 - workers: - - id: worker - enabled: true - http: - uri: ${env:ARCADE_WORKER_URI} - timeout: 30 - retry: 3 - secret: ${env:ARCADE_WORKER_SECRET} -``` - -### engine.env - -```bash -### Engine configuration ### -API_DEVELOPMENT=true -ARCADE_API_HOST=localhost -ARCADE_API_PORT=9099 -ANALYTICS_ENABLED=true - -# Encryption keys (change this when deploying to production) -ROOT_KEY_1=default-key-value - -### Model Provider API keys ### -# OPENAI_API_KEY= -# ANTHROPIC_API_KEY= -# GROQ_API_KEY= - - -### Security configuration ### -ROOT_KEY_1= - - -### Storage configuration ### -# POSTGRES_USER= -# POSTGRES_PASSWORD= -# POSTGRES_HOST= -# POSTGRES_PORT= -# POSTGRES_DB= - - -### Telemetry (OTEL) configuration ### -TELEMETRY_ENVIRONMENT=local -TELEMETRY_LOGGING_LEVEL=debug -TELEMETRY_LOGGING_ENCODING=console - - -### Worker Configuration ### -ARCADE_WORKER_URI=http://localhost:8002 -ARCADE_WORKER_SECRET=dev - - -# OAuth Providers -ATLASSIAN_CLIENT_ID="" -ATLASSIAN_CLIENT_SECRET= - -DISCORD_CLIENT_ID="" -DISCORD_CLIENT_SECRET= - -DROPBOX_CLIENT_ID="" -DROPBOX_CLIENT_SECRET= - -GITHUB_CLIENT_ID="" -GITHUB_CLIENT_SECRET= - -GOOGLE_CLIENT_ID="" -GOOGLE_CLIENT_SECRET= - -LINKEDIN_CLIENT_ID="" -LINKEDIN_CLIENT_SECRET= - -MICROSOFT_CLIENT_ID="" -MICROSOFT_CLIENT_SECRET= - -REDDIT_CLIENT_ID="" -REDDIT_CLIENT_SECRET= - -SLACK_CLIENT_ID="" -SLACK_CLIENT_SECRET= - -SPOTIFY_CLIENT_ID="" -SPOTIFY_CLIENT_SECRET= - -TWITCH_CLIENT_ID="" -SPOTIFY_CLIENT_SECRET= - -X_CLIENT_ID="" -X_CLIENT_SECRET= - -ZOOM_CLIENT_ID="" -ZOOM_CLIENT_SECRET= -``` diff --git a/app/en/home/deployment/on-prem-mcp/page.mdx b/app/en/home/deployment/on-prem-mcp/page.mdx deleted file mode 100644 index 21f55a3de..000000000 --- a/app/en/home/deployment/on-prem-mcp/page.mdx +++ /dev/null @@ -1,320 +0,0 @@ ---- -title: "On-premises MCP Servers" -description: "Learn how to deploy MCP servers in a hybrid architecture" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# On-premise MCP Servers - - - - -An on-premises MCP server deployment allows you to execute tools in your own environment while still leveraging Arcade's cloud Engine infrastructure. This gives you the flexibility to access private resources, maintain data security, and customize your environment while leveraging Arcade's MCP server management and federation capabilities. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [Arcade CLI](/home/quickstart) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- How to run your MCP server with HTTP transport -- How to create a secure tunnel to expose it publicly -- How to register your server in Arcade -- How to test your server with the Arcade Playground - - - - -## How on-premises MCP servers work - -You can make your MCP server accessible to others by exposing it through a secure tunnel and registering it with Arcade. This allows remote users and services to interact with your tools without deploying to a cloud platform. - -The on-premises MCP server model uses a bidirectional connection between your local environment and Arcade's cloud engine: - -1. You run the Arcade MCP server in your environment (on-premises, private cloud, etc.) -2. Your MCP server is exposed to Arcade's cloud engine using a public URL -3. The Arcade cloud engine routes tool calls to your MCP server -4. Your MCP server processes the requests and returns responses to the engine - -## Benefits of on-premises MCP servers - -- **Resource access**: Access private databases, APIs, and other resources not accessible from Arcade's cloud -- **Data control**: Keep sensitive data within your environment while still using Arcade's capabilities -- **Custom environments**: Use specific dependencies or configurations required by your tools -- **Compliance**: Meet regulatory requirements by keeping data processing within your infrastructure - -## Setting up an on-premises MCP server - - - -### Setup your MCP Servers - -Follow the [Creating a MCP Server](/home/build-tools/create-a-mcp-server) guide to create your MCP Server. - -### Start your local MCP Server - -Ensure you are logged in to Arcade: - - - - -```bash -arcade login -``` - - - - -Add the environment variables to your shell: - -```bash -export ARCADE_API_KEY= -export ARCADE_USER_ID= -``` - -or to a `.env` file: - -```env filename=".env" -ARCADE_API_KEY= -ARCADE_USER_ID= -``` - - - - -Start your MCP server with HTTP transport: - -```bash -# Navigate to your entrypoint file -cd my_server/src/my_server - -# Run with HTTP transport (default) -uv run server.py -uv run server.py http -``` - -Your server will start on `http://localhost:8000`. Keep this terminal running. - -## Create a Secure Tunnel - -Open a **separate terminal** and create a tunnel using one of these options: - -- [ngrok](https://ngrok.com) is easy to set up and works across all platforms. -- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) provides persistent URLs and advanced features. -- [Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) is ideal for sharing within a team or organization. - - - - [ngrok](https://ngrok.com) is easy to set up and works across all platforms. - -1. **Install ngrok:** - - ```bash - # macOS - brew install ngrok - - # Or download from https://ngrok.com/download - ``` - -2. **Create a tunnel:** - - ```bash - ngrok http 8000 - ``` - -3. **Copy your URL:** - Look for the "Forwarding" line in the ngrok output: - - ``` - Forwarding https://abc123.ngrok-free.app -> http://localhost:8000 - ``` - - Copy the `https://abc123.ngrok-free.app` URL - this is your public URL. - -**Pros:** - -- Quick setup, no account required for basic use -- Automatic HTTPS -- Web dashboard to inspect requests - -**Cons:** - -- Free tier URLs change on each restart -- May show interstitial page for free tier - - - - - -[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) provides persistent URLs and advanced features. - -1. **Install cloudflared:** - - ```bash - # macOS - brew install cloudflare/cloudflare/cloudflared - - # Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/ - ``` - -2. **Create a tunnel:** - - ```bash - cloudflared tunnel --url http://localhost:8000 - ``` - -3. **Copy your URL:** - Look for the "Your quick Tunnel has been created" message with your URL. - -**Pros:** - -- Free tier includes persistent URLs (with setup) -- Built-in DDoS protection -- Access control features - -**Cons:** - -- Requires Cloudflare account for persistent URLs -- More complex setup for advanced features - - - - - -[Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) is ideal for sharing within a team or organization. - -1. **Install Tailscale:** - - ```bash - # macOS - brew install tailscale - - # Or download from https://tailscale.com/download - ``` - -2. **Authenticate:** - - ```bash - tailscale up - ``` - -3. **Create a funnel:** - - ```bash - tailscale funnel 8000 - ``` - -4. **Get your URL:** - Tailscale will display your funnel URL (e.g., `https://my-machine.tail-scale.ts.net`) - -**Pros:** - -- Persistent URLs tied to your machine -- Private by default (only shared with specified users) -- No bandwidth limits - -**Cons:** - -- Requires Tailscale account -- Best for team/organization use cases - - - - -### Register your MCP Server in Arcade - -Once you have a public URL, register your MCP server in the Arcade dashboard to make it accessible through the Arcade API. - -1. **Navigate to the MCP Servers page** in your [Arcade dashboard](https://api.arcade.dev/dashboard/servers) - -2. **Click "Add Server"** - -3. **Fill in the registration form:** - - - **ID**: Choose a unique identifier (e.g., `my-mcp-server`) - - **Server Type**: Select "Arcade" - - **URL**: Enter your public tunnel URL from Step 2 - - **Secret**: Enter a secret for your server (or use `dev` for testing) - - **Timeout**: Configure request timeout (default: 30s) - - **Retry**: Configure retry attempts (default: 3) - -4. **Click "Create"** - -Here's an example of a configuration: - -```yaml -ID: my-mcp-server -Server Type: Arcade -URL: https://abc123.ngrok-free.app -Secret: my-secure-secret-123 -Timeout: 30s -Retry: 3 -``` - -### Test the connection to your MCP Server - -You can now test your MCP Server by making requests using the Playground, or an MCP client: - - - - -1. **Go to the [Arcade Playground](https://api.arcade.dev/dashboard/playground/chat)** - -2. **Select your MCP server** from the dropdown - -3. **Choose a tool** from your server - -4. **Execute the tool** with test parameters - -5. **Verify the response:** - - Check that the response is correct - - View request logs in your local server terminal - - Inspect the tunnel dashboard for request details - - - - -1. Use an app that supports MCP clients, like AI assistants and IDEs: - - [Visual Studio Code](/home/mcp-clients/visual-studio-code) - - [Claude Desktop](/home/mcp-clients/claude-desktop) - - [Cursor](/home/mcp-clients/cursor) -1. Enable your MCP Server from the list of available MCP Servers -1. Verify that the response is correct and you see request logs in your MCP Server - - - - - - -## Key Concepts - -- **HTTP Transport** Run your server with HTTP transport to expose your tools via a REST/SSE API -- **Secure Tunnels** Create a secure tunnel to expose your server publicly -- **Arcade Registration** Register your server in Arcade to make it accessible through the Arcade API -- **Playground Testing** Test your server with the Arcade Playground - -## Best practices - -- **Persistent URLs**: For production use, set up a persistent public URL rather than ephemeral ones -- **TLS**: Use a TLS-enabled URL for production use -- **Monitoring**: Set up monitoring for your MCP Server to ensure availability - -## Troubleshooting - -- **Connection issues**: Ensure your public URL is accessible and that your local MCP Server is running -- **Timeout errors**: If your MCP Server takes too long to respond, increase the timeout value in the MCP Server configuration - -## Next steps - -- [Create custom tools](/home/build-tools/create-a-mcp-server) for your MCP Server -- [Set up authentication](/home/build-tools/create-a-tool-with-auth) for secure access to resources -- [Configure secrets](/home/build-tools/create-a-tool-with-secrets) for your MCP Server diff --git a/app/en/home/evaluate-tools/_meta.tsx b/app/en/home/evaluate-tools/_meta.tsx deleted file mode 100644 index bc4929294..000000000 --- a/app/en/home/evaluate-tools/_meta.tsx +++ /dev/null @@ -1,5 +0,0 @@ -export default { - "why-evaluate-tools": "Why evaluate tools?", - "create-an-evaluation-suite": "Create an evaluation suite", - "run-evaluations": "Run evaluations", -}; diff --git a/app/en/home/evaluate-tools/create-an-evaluation-suite/page.mdx b/app/en/home/evaluate-tools/create-an-evaluation-suite/page.mdx deleted file mode 100644 index c82f8e626..000000000 --- a/app/en/home/evaluate-tools/create-an-evaluation-suite/page.mdx +++ /dev/null @@ -1,319 +0,0 @@ ---- -title: "Create an evaluation suite" -description: "Learn how to evaluate your tools using Arcade" ---- - -# Evaluate tools - -In this guide, you'll learn how to evaluate your tools to ensure they are selected and used correctly by an AI model. You'll define evaluation cases and use different critics to assess the outcome of your evaluations. - -We'll create evaluation cases to test the `greet` tool and measure its performance. - -import { Steps, Tabs, Callout } from "nextra/components"; - - - -### Prerequisites - -- [Create an MCP Server](/home/build-tools/create-a-mcp-server) -- Install the evaluation dependencies: - - - - - ```bash - uv tool install 'arcade-mcp[evals]' - ``` - - - - - - ```bash - pip install 'arcade-mcp[evals]' - ``` - - - - -### Create an evaluation suite - -Navigate to your MCP Server's directory - -```bash -cd my_server -``` - -Create a new Python file for your evaluations, e.g., `eval_server.py`. - - - For evals, the file name should start with `eval_` and be a Python script - (using the `.py` extension). - - -### Define your evaluation cases - -Open `eval_server.py` and add the following code: - -```python -from arcade_evals import ( - EvalSuite, tool_eval, EvalRubric, - ExpectedToolCall, BinaryCritic -) -from arcade_core import ToolCatalog - -from server import greet - -# Create a catalog of tools to include in the evaluation -catalog = ToolCatalog() -catalog.add_tool(greet, "Greet") - -# Create rubric with tool calls -rubric = EvalRubric( - fail_threshold=0.8, - warn_threshold=0.9, -) - -@tool_eval() -def hello_eval_suite() -> EvalSuite: - """Create an evaluation suite for the hello tool.""" - suite = EvalSuite( - name="MCP Server Evaluation", - catalog=catalog, - system_message="You are a helpful assistant.", - rubric=rubric, - ) - - suite.add_case( - name="Simple Greeting", - user_message="Greet Alice", - expected_tool_calls=[ - ExpectedToolCall( - func=greet, - args={ - "name": "Alice", - }, - ) - ], - critics=[ - BinaryCritic(critic_field="name", weight=1.0), - ], - ) - - return suite -``` - -### Run the evaluation - -From the server directory, ensure you have an OpenAI API key set in the `OPENAI_API_KEY` environment variable. Then run: - -```bash -export OPENAI_API_KEY= -arcade evals . -``` - -This command executes your evaluation suite and provides a report. - - - By default, the evaluation suite will use the `gpt-4o` model. You can specify - a different model and provider using the `--models` and `--provider` options. - If you are using a different provider, you will need to set the appropriate - API key in an environment variable, or use the `--provider-api-key` option. - For more information, see the [Run - evaluations](/home/evaluate-tools/run-evaluations) guide. - - -### How it works - -The evaluation framework in Arcade allows you to define test cases (`EvalCase`) with expected tool calls and use critics to assess an AI model's performance. - -Similar to how a unit test suite measures the validity and performance of a function, an eval suite measures how well an AI model understands and uses your tools. - -### Next steps - -- Explore [different types of critics](#critic-classes) and [more complex evaluation cases](#advanced-evaluation-cases) to thoroughly test your tools. -- Understand [how to specify options for your evaluation runs](/home/evaluate-tools/run-evaluations). - - - -## Critic classes - -Critics are used to evaluate the correctness of tool calls. For simple tools, "correct" might be binary: is it exactly what we expected? For more complex tools, we might need to evaluate the similarity between expected and actual values, or measure numeric values within an acceptable range. - -Arcade's evaluation framework provides several critic classes to help you evaluate both exact and "fuzzy" matches between expected and actual values when a model predicts the parameters of a tool call. - -### BinaryCritic - -Checks if a parameter value matches exactly. - -```python -BinaryCritic(critic_field="name", weight=1.0) -``` - -### SimilarityCritic - -Evaluates the similarity between expected and actual values. - -```python -from arcade_evals import SimilarityCritic - -SimilarityCritic(critic_field="message", weight=1.0) -``` - -### NumericCritic - -Assesses numeric values within a specified tolerance. - -```python -from arcade_evals import NumericCritic - -NumericCritic(critic_field="score", tolerance=0.1, weight=1.0) -``` - -### DatetimeCritic - -Evaluates the closeness of datetime values within a specified tolerance. - -```python -from datetime import timedelta -from arcade_evals import DatetimeCritic - -DatetimeCritic(critic_field="start_time", tolerance=timedelta(seconds=10), weight=1.0) -``` - -## Advanced evaluation cases - -You can add more evaluation cases to test different scenarios. - - - Ensure that your `greet` tool and evaluation cases are updated accordingly and - that you rerun `arcade evals .` to test your changes. - - If your evals fail, use `--details` to see the detailed feedback from each critic. See [Run evaluations](/home/evaluate-tools/run-evaluations) to understand the options available in `arcade evals`. - - - -### Example: Greeting with emotion - -Modify your `hello` tool to accept an `emotion` parameter: - -```python -from enum import Enum - -class Emotion(str, Enum): - HAPPY = "happy" - SLIGHTLY_HAPPY = "slightly happy" - SAD = "sad" - SLIGHTLY_SAD = "slightly sad" - -@app.tool -def greet( - name: Annotated[str, "The name of the person to greet"], - emotion: Annotated[ - Emotion, "The emotion to convey. Defaults to happy if omitted." - ] = Emotion.HAPPY, -) -> Annotated[str, "A greeting to the user"]: - """ - Greet a person by name, optionally with a specific emotion. - """ - return f"Hello {name}! I'm feeling {emotion.value} today." -``` - -Add an evaluation case for this new parameter: - -```python -# At the top of the file: -from server import Emotion -from arcade_evals import SimilarityCritic - -# Inside hello_eval_suite(): -suite.add_case( - name="Greeting with Emotion", - user_message="Say hello to Bob sadly", - expected_tool_calls=[ - ExpectedToolCall( - func=greet, - args={ - "name": "Bob", - "emotion": Emotion.SAD, - }, - ) - ], - critics=[ - BinaryCritic(critic_field="name", weight=0.5), - SimilarityCritic(critic_field="emotion", weight=0.5), - ], -) -``` - -Add an evaluation case with additional conversation context: - -```python -suite.add_case( - name="Greeting with Emotion from Context", - user_message="Say hello to Bob based on my current mood.", - expected_tool_calls=[ - ExpectedToolCall( - func=greet, - args={ - "name": "Bob", - "emotion": Emotion.HAPPY, - }, - ) - ], - critics=[ - BinaryCritic(critic_field="name", weight=0.5), - SimilarityCritic(critic_field="emotion", weight=0.5), - ], - # Add some context to the evaluation case - additional_messages= [ - {"role": "user", "content": "Hi, I'm so happy!"}, - { - "role": "assistant", - "content": "That's awesome! What's got you feeling so happy today?", - }, - ] -) -``` - -Add an evaluation case with multiple expected tool calls: - -```python -suite.add_case( - name="Multiple Greetings with Emotion from Context", - user_message="Say hello to Bob based on my current mood. And then say hello to Alice with slightly less of that emotion.", - expected_tool_calls=[ - ExpectedToolCall( - func=greet, - args={ - "name": "Bob", - "emotion": Emotion.HAPPY, - }, - ), - ExpectedToolCall( - func=greet, - args={ - "name": "Alice", - "emotion": Emotion.SLIGHTLY_HAPPY, - }, - ) - ], - critics=[ - BinaryCritic(critic_field="name", weight=0.5), - SimilarityCritic(critic_field="emotion", weight=0.5), - ], - # Add some context to the evaluation case - additional_messages= [ - {"role": "user", "content": "Hi, I'm so happy!"}, - { - "role": "assistant", - "content": "That's awesome! What's got you feeling so happy today?", - }, - ] -) -``` - -## Next steps - -- **See an example MCP server with evaluations**: [Source code of a server with evaluations](https://github.com/ArcadeAI/arcade-mcp/tree/139cc2e54db0e5815f1c79dbe9e3285b4fe2bd66/examples/mcp_servers/server_with_evaluations) -- **Learn how to run evaluations**: [Run evaluations](/home/evaluate-tools/run-evaluations) diff --git a/app/en/home/evaluate-tools/run-evaluations/page.mdx b/app/en/home/evaluate-tools/run-evaluations/page.mdx deleted file mode 100644 index 0920ed24c..000000000 --- a/app/en/home/evaluate-tools/run-evaluations/page.mdx +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: "Run evaluations" -description: "Learn how to run evaluations using Arcade" ---- - -# Run evaluations with the Arcade CLI - -The Arcade Evaluation Framework allows you to run evaluations of your tool-enabled language models conveniently using the Arcade CLI. This enables you to execute your evaluation suites, gather results, and analyze the performance of your models in an efficient and streamlined manner. - - - - -Run evaluations of your tool-enabled language models using the Arcade CLI. - - - - - -- [Arcade CLI](/home/arcade-cli) -- [An MCP Server](/home/build-tools/create-a-mcp-server) -- [Create an evaluation suite](/home/evaluate-tools/create-an-evaluation-suite) - - - - - -- How to use the `arcade evals` CLI command to run evaluations. - - - - -### Using the `arcade evals` Command - -To run evaluations, use the `arcade evals` command provided by the Arcade CLI. This command searches for evaluation files in the specified directory, executes any functions decorated with `@tool_eval`, and displays the results. - -#### Basic Usage - -```bash -arcade evals -``` - -- ``: The directory containing your evaluation files. By default, it searches the current directory (`.`). - -For example, to run evaluations in the current directory: - -```bash -arcade evals -``` - -#### Evaluation File Naming Convention - -The `arcade evals` command looks for Python files that start with `eval_` and end with `.py` (e.g., `eval_math_tools.py`, `eval_slack_messaging.py`). These files should contain your evaluation suites. - -#### Command Options - -The `arcade evals` command supports several options to customize the evaluation process: - -- `--details`, `-d`: Show detailed results for each evaluation case, including critic feedback. - - Example: - - ```bash - arcade evals --details . - ``` - -- `--models`, `-m`: Specify the models to use for evaluation. Provide a comma-separated list of model names. - - Example: - - ```bash - arcade evals --models gpt-4o,gpt-5 . - ``` - -- `--max-concurrent`, `-c`: Set the maximum number of concurrent evaluations to run in parallel. - - Example: - - ```bash - arcade evals --max-concurrent 4 . - ``` - -- `--provider`, `-p`: The provider of the models to use for evaluation. Uses OpenAI by default. - - Example: - - ```bash - arcade evals --provider openai . - ``` - -- `--provider-api-key`, `-k`: The model provider API key. If not provided, will look for the appropriate environment variable based on the provider (e.g., OPENAI_API_KEY for openai provider), first in the current environment, then in the current working directory's .env file. - - Example: - - ```bash - arcade evals --provider-api-key my-api-key . - ``` - -- `--debug`: Show debug information in the CLI. - - Example: - - ```bash - arcade evals --debug . - ``` - -- `--help`: Show help information and exit. - - Example: - - ```bash - arcade evals --help - ``` - -#### Example Command - -Running evaluations in the `arcade_my_tools/evals` directory, showing detailed results, using the `gpt-5` model: - -```bash -arcade evals arcade_my_tools/evals --details --models gpt-5 -k my-openai-api-key -``` - -### Execution Process - -When you run the `arcade evals` command, the following steps occur: - -1. **Preparation**: The CLI loads the evaluation suites from the specified directory, looking for files that match the naming convention. - -2. **Execution**: The evaluation suites are executed asynchronously. Each suite's evaluation function, decorated with `@tool_eval`, is called with the appropriate configuration, including the model and concurrency settings. - -3. **Concurrency**: Evaluations can run concurrently based on the `--max-concurrent` setting, improving efficiency. - -4. **Result Aggregation**: Results from all evaluation cases and models are collected and aggregated. - -### Displaying Results - -After the evaluations are complete, the results are displayed in a concise and informative format, similar to testing frameworks like `pytest`. The output includes: - -- **Summary**: Shows the total number of cases, how many passed, failed, or issued warnings. - - Example: - - ``` - Summary -- Total: 5 -- Passed: 4 -- Failed: 1 - ``` - -- **Detailed Case Results**: For each evaluation case, the status (PASSED, FAILED, WARNED), the case name, and the score are displayed. - - Example: - - ``` - PASSED Add two large numbers -- Score: 1.00 - FAILED Send DM with ambiguous username -- Score: 0.75 - ``` - -- **Critic Feedback**: If the `--details` flag is used, detailed feedback from each critic is provided, highlighting matches, mismatches, and scores for each evaluated field. - - Example: - - ``` - Details: - user_name: - Match: False, Score: 0.00/0.50 - Expected: johndoe - Actual: john_doe - message: - Match: True, Score: 0.50/0.50 - ``` - -### Interpreting the Results - -- **Passed**: The evaluation case met or exceeded the fail threshold specified in the rubric. - -- **Failed**: The evaluation case did not meet the fail threshold. - -- **Warnings**: If the score is between the warn threshold and the fail threshold, a warning is issued. - -Use the detailed feedback to understand where the model's performance can be improved, particularly focusing on mismatches identified by critics. - -### Customizing Evaluations - -You can customize the evaluation process by adjusting: - -- **Rubrics**: Modify fail and warn thresholds, and adjust weights to emphasize different aspects of evaluation. - -- **Critics**: Add or modify critics in your evaluation cases to target specific arguments or behaviors. - -- **Concurrency**: Adjust the `--max-concurrent` option to optimize performance based on your environment. - -### Handling Multiple Models - -You can evaluate multiple models in a single run by specifying them in the `--models` option as a comma-separated list. This allows you to compare the performance of different models across the same evaluation suites. - -Example: - -```bash -arcade evals . --models gpt-4o,gpt-5 -``` - -### Considerations - -- **Evaluation Files**: Ensure your evaluation files are correctly named and contain the evaluation suites decorated with `@tool_eval`. - -- **Provider API Keys**: If you are using a different provider, you will need to set the appropriate API key in an environment variable, or use the `--provider-api-key` option. - -- **Tool Catalog**: Ensure your tool catalog is correctly defined and includes all the tools you want to evaluate. - -- **Weight distribution**: Ensure your weight distribution reflects the importance of each critic and that the sum of the weights is `1.0`. - -## Conclusion - -Running evaluations using the Arcade CLI provides a powerful and convenient way to assess the tool-calling capabilities of your language models. By leveraging the `arcade evals` command, you can efficiently execute your evaluation suites, analyze results, and iterate on your models and tools. - -Integrating this evaluation process into your development workflow helps ensure that your models interact with tools as expected, enhances reliability, and builds confidence in deploying actionable language models in production environments. - -## Next steps - -- **See an example MCP server with evaluations**: [Source code of a server with evaluations](https://github.com/ArcadeAI/arcade-mcp/tree/139cc2e54db0e5815f1c79dbe9e3285b4fe2bd66/examples/mcp_servers/server_with_evaluations) diff --git a/app/en/home/evaluate-tools/why-evaluate-tools/page.mdx b/app/en/home/evaluate-tools/why-evaluate-tools/page.mdx deleted file mode 100644 index 4f2af3a55..000000000 --- a/app/en/home/evaluate-tools/why-evaluate-tools/page.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "Why evaluate tools?" -description: "Learn why evaluating your tools is important" ---- - -# Why evaluate tools? - -
-
- When deploying language models with tool-calling capabilities in production environments, it's essential to ensure their effectiveness and reliability. This evaluation process goes beyond traditional testing and focuses on two key aspects: - - 1. **Tool Utilization**: Assessing how efficiently the language model uses the available tools. - 2. **Intent Understanding**: Evaluating the language model's ability to comprehend user intents and select the appropriate tools to fulfill those intents. - - Arcade's Evaluation Framework provides a comprehensive approach to assess and validate the tool-calling capabilities of language models, ensuring they meet the high standards required for real-world applications. -
- -
- -## Why Evaluate Tool Calling by Task? - -Language models augmented with tool-use capabilities can perform complex tasks by invoking external tools or APIs. However, without proper evaluation, these models might: - -- **Misinterpret user intents**, leading to incorrect tool selection. -- **Provide incorrect arguments** to tools, causing failures or undesired outcomes. -- **Fail to execute the necessary sequence of tool calls**, especially in tasks requiring multiple steps. - -Evaluating tool calling by task ensures that the language model can handle specific scenarios reliably, providing confidence in its performance in production settings. - -## Evaluation Scoring - -Scoring in the evaluation framework is based on comparing the model's actual tool calls with the expected ones for each evaluation case. The total score for a case depends on: - -1. **Tool Selection**: Whether the model selected the correct tools for the task. -2. **Tool Call Arguments**: The correctness of the arguments provided to the tools, evaluated by critics. -3. **Evaluation Rubric**: Each aspect of the evaluation is weighted according to the rubric, affecting its impact on the final score. - -The evaluation result includes: - -- **Score**: A normalized value between 0.0 and 1.0. -- **Result**: - - _Passed_: Score is above the fail threshold. - - _Failed_: Score is below the fail threshold. - - _Warned_: Score is between the warning and fail thresholds. - -## Critics: Types and Usage - -Critics are essential for evaluating the correctness of tool call arguments. Different types of critics serve various evaluation needs: - -### BinaryCritic - -`BinaryCritic`s check for exact matches between expected and actual values after casting. - -- **Use Case**: When exact values are required (e.g., specific numeric parameters). -- **Example**: Ensuring the model provides the exact user ID in a function call. - -### NumericCritic - -`NumericCritic` evaluates numeric values within a specified range, allowing for acceptable deviations. - -- **Use Case**: When values can be approximate but should be within a certain threshold. -- **Example**: Accepting approximate results in mathematical computations due to floating-point precision. - -### SimilarityCritic - -`SimilarityCritic` measures the similarity between expected and actual string values using metrics like cosine similarity. - -- **Use Case**: When the exact wording isn't critical, but the content should be similar. -- **Example**: Evaluating if the message content in a communication tool is similar to the expected message. - -### DatetimeCritic - -`DatetimeCritic` evaluates the closeness of datetime values within a specified tolerance. - -- **Use Case**: When datetime values should be within a certain range of the expected time. -- **Example**: Verifying if a scheduled event time is close enough to the intended time. - -### Choosing the Right Critic - -- **Exact Matches Needed**: Use **BinaryCritic** for strict equality. -- **Numeric Ranges**: Use **NumericCritic** when a tolerance is acceptable. -- **Textual Similarity**: Use **SimilarityCritic** for comparing messages or descriptions. -- **Datetime Tolerance**: Use **DatetimeCritic** when a tolerance is acceptable for datetime comparisons. - -Critics are defined with fields such as `critic_field`, `weight`, and parameters specific to their types (e.g., `similarity_threshold` for `SimilarityCritic`). - -## Rubrics and Setting Thresholds - -An **EvalRubric** defines the evaluation criteria and thresholds for determining pass/fail outcomes. Key components include: - -- **Fail Threshold**: The minimum score required to pass the evaluation. -- **Warn Threshold**: The score threshold for issuing a warning. -- **Weights**: Assigns importance to different aspects of the evaluation (e.g., tool selection, argument correctness). - -### Setting Up a Rubric - -- **Define Fail and Warn Thresholds**: Choose values between 0.0 and 1.0 to represent acceptable performance levels. -- **Assign Weights**: Allocate weights to tool selection and critics to reflect their importance in the overall evaluation. -- **Configure Failure Conditions**: Set flags like `fail_on_tool_selection` to enforce strict criteria. - -### Example Rubric Configuration: - -A rubric that requires a score of at least 0.85 to pass and issues a warning if the score is between 0.85 and 0.95: - -- Fail Threshold: 0.85 -- Warn Threshold: 0.95 -- Fail on Tool Selection: True -- Tool Selection Weight: 1.0 - -```python -rubric = EvalRubric( - fail_threshold=0.85, - warn_threshold=0.95, - fail_on_tool_selection=True, - tool_selection_weight=1.0, -) -``` - -## Building an Evaluation Suite - -An **EvalSuite** orchestrates the running of multiple evaluation cases. Here's how to build one: - -1. **Initialize EvalSuite**: Provide a name, system message, tool catalog, and rubric. -2. **Add Evaluation Cases**: Use `add_case` or `extend_case` to include various scenarios. -3. **Specify Expected Tool Calls**: Define the tools and arguments expected for each case. -4. **Assign Critics**: Attach critics relevant to each case to evaluate specific arguments. -5. **Run the Suite**: Execute the suite using the Arcade CLI to collect results. - -### Example: Math Tools Evaluation Suite - -An evaluation suite for math tools might include cases such as: - -- **Adding Two Large Numbers**: - - **User Message**: "Add 12345 and 987654321" - - **Expected Tool Call**: `add(a=12345, b=987654321)` - - **Critics**: - - `BinaryCritic` for arguments `a` and `b` -- **Calculating Square Roots**: - - **User Message**: "What is the square root of 3224990521?" - - **Expected Tool Call**: `sqrt(a=3224990521)` - - **Critics**: - - `BinaryCritic` for argument `a` - -### Example: Slack Messaging Tools Evaluation Suite - -An evaluation suite for Slack messaging tools might include cases such as: - -- **Sending a Direct Message**: - - **User Message**: "Send a direct message to johndoe saying 'Hello, can we meet at 3 PM?'" - - **Expected Tool Call**: `send_dm_to_user(user_name='johndoe', message='Hello, can we meet at 3 PM?')` - - **Critics**: - - `BinaryCritic` for `user_name` - - `SimilarityCritic` for `message` -- **Posting a Message to a Channel**: - - **User Message**: "Post 'The new feature is now live!' in the #announcements channel" - - **Expected Tool Call**: `send_message_to_channel(channel_name='announcements', message='The new feature is now live!')` - - **Critics**: - - `BinaryCritic` for `channel_name` - - `SimilarityCritic` for `message` diff --git a/app/en/home/google-adk/_meta.tsx b/app/en/home/google-adk/_meta.tsx index e208ebdc0..e0b5f430e 100644 --- a/app/en/home/google-adk/_meta.tsx +++ b/app/en/home/google-adk/_meta.tsx @@ -1,4 +1,4 @@ export default { - overview: "Overview", - "use-arcade-tools": "Using Arcade tools", + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", }; diff --git a/app/en/home/google-adk/overview/page.mdx b/app/en/home/google-adk/overview/page.mdx deleted file mode 100644 index c13cc7eaa..000000000 --- a/app/en/home/google-adk/overview/page.mdx +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "Arcade with Google ADK overview" -description: "Comprehensive guide to using Arcade with the Google ADK library" ---- - -# Arcade with Google ADK - -The `google-adk-arcade` package provides a seamless integration between -[Arcade](https://arcade.dev) and the [Google ADK](https://github.com/google/adk-python/). This integration allows you to enhance your AI agents with powerful Arcade tools including Google Mail, LinkedIn, GitHub, and many more. - -## Installation - -Install the necessary packages to get started: - -```bash -pip install google-adk-arcade -``` - -Make sure you have your Arcade API key ready. [Get an API key](/home/api-keys) if you don't already have one. - -## Key features - -- **Easy integration** with the Google ADK framework -- **Access to all Arcade MCP Servers** including Google, GitHub, LinkedIn, X, and more -- **Create custom tools** with the Arcade Tool SDK -- **Manage user authentication** for tools that require it -- **Asynchronous support** compatible with Google's ADK framework - -## Basic usage - -Here's a simple example of using Arcade tools with OpenAI Agents: - -```python -import asyncio - -from arcadepy import AsyncArcade -from google.adk import Agent, Runner -from google.adk.artifacts import InMemoryArtifactService -from google.adk.sessions import InMemorySessionService -from google.genai import types - -from google_adk_arcade.tools import get_arcade_tools - - -async def main(): - app_name = 'my_app' - user_id = '{arcade_user_id}' - session_service = InMemorySessionService() - artifact_service = InMemoryArtifactService() - client = AsyncArcade() - - google_tools = await get_arcade_tools(client, tools=["Gmail.ListEmails"]) - - # authorize the tools - for tool in google_tools: - result = await client.tools.authorize( - tool_name=tool.name, - user_id=user_id - ) - if result.status != "completed": - print(f"Click this link to authorize {tool.name}:\n{result.url}") - await client.auth.wait_for_completion(result) - - # create the agent - google_agent = Agent( - model="gemini-2.0-flash", - name="google_tool_agent", - instruction="I can use Google tools to manage an inbox!", - description="An agent equipped with tools to read Gmail emails." - tools=google_tools, - ) - - #create the session and pass the user ID to the state - session = await session_service.create_session( - app_name=app_name, user_id=user_id, state={ - "user_id": user_id, - } - ) - - runner = Runner( - app_name=app_name, - agent=google_agent, - artifact_service=artifact_service, - session_service=session_service, - ) - - user_input = "summarize my latest 3 emails" - content = types.Content( - role='user', parts=[types.Part.from_text(text=user_input)] - ) - for event in runner.run( - user_id=user_id, - session_id=session.id, - new_message=content, - ): - if event.content.parts and event.content.parts[0].text: - print(f'** {event.author}: {event.content.parts[0].text}') - -if __name__ == '__main__': - asyncio.run(main()) -``` - -## Handling authorization - -When a user needs to authorize access to a tool (like Google or GitHub), -the agent will reply with a URL for the user to visit, which will be displayed -to the user. - -After visiting the URL and authorizing access, the user can run the agent again -with the same `user_id`, and it will work without requiring re-authorization. - -Alternatively, you can authorize the tool before running the agent: - -```python -# authorize the tools -for tool in google_tools: - result = await client.tools.authorize( - tool_name=tool.name, - user_id=user_id - ) - if result.status != "completed": - print(f"Click this link to authorize {tool.name}:\n{result.url}") - await client.auth.wait_for_completion(result) -``` - -## Next steps - -Ready to start building with Arcade and OpenAI Agents? Check out these guides: - -- [Using Arcade tools](/home/google-adk/use-arcade-tools) - Learn the basics of using Arcade tools with Google ADK -- [Creating custom tools](/home/build-tools/create-a-mcp-server) - Build your own tools with the Arcade Tool SDK - -Enjoy exploring Arcade and building powerful AI-enabled applications! diff --git a/app/en/home/google-adk/quickstart-python/page.mdx b/app/en/home/google-adk/quickstart-python/page.mdx new file mode 100644 index 000000000..5f28a1305 --- /dev/null +++ b/app/en/home/google-adk/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Google ADK with Python. \ No newline at end of file diff --git a/app/en/home/google-adk/quickstart-typescript/page.mdx b/app/en/home/google-adk/quickstart-typescript/page.mdx new file mode 100644 index 000000000..712d31c41 --- /dev/null +++ b/app/en/home/google-adk/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Google ADK with TypeScript. \ No newline at end of file diff --git a/app/en/home/google-adk/use-arcade-tools/page.mdx b/app/en/home/google-adk/use-arcade-tools/page.mdx deleted file mode 100644 index 6bede0d04..000000000 --- a/app/en/home/google-adk/use-arcade-tools/page.mdx +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: "Use Arcade with Google ADK" -description: "Integrate Arcade tools into your Google ADK applications" ---- - -import { Steps } from "nextra/components"; - -## Use Arcade with Google ADK - -In this guide, let's explore how to integrate Arcade tools into your Google ADK application. Follow the step-by-step instructions below. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Set up your environment - -Install the required packages, and ensure your environment variables are set with your Arcade API key: - -```bash -pip install google-adk-arcade -``` - -### Configure API keys - -Provide your Arcade and Google API keys. You can store it in environment variables or directly in your code: - -> Need an Arcade API key? Visit the [Get an API key](/home/api-keys) page to create one. - -```bash -export ARCADE_API_KEY='YOUR_ARCADE_API_KEY' -export GOOGLE_API_KEY='YOUR_GOOGLE_API_KEY' -export GOOGLE_GENAI_USE_VERTEXAI=FALSE -``` - -### Create and manage Arcade tools - -Use the `get_arcade_tools` function to retrieve tools from specific MCP Servers: - -```python -from arcadepy import AsyncArcade -from google_adk_arcade.tools import get_arcade_tools - -# Initialize the Arcade client -client = AsyncArcade() - -# Get all tools from the "Gmail" MCP Server -tools = await get_arcade_tools(client, toolkits=["gmail"]) - -# You can request multiple MCP Servers at once -tools = await get_arcade_tools(client, toolkits=["gmail", "github", "linkedin"]) - -# You can request specific tools -tools = await get_arcade_tools(client, tools=["Gmail_ListEmails", "Slack_ListUsers", "Slack_SendDmToUser"]) -``` -### Authorize the tools - -Enable the tools for your agents: - -```python -# authorize the tools -for tool in google_tools: - result = await client.tools.authorize( - tool_name=tool.name, - user_id=user_id - ) - if result.status != "completed": - print(f"Click this link to authorize {tool.name}:\n{result.url}") - await client.auth.wait_for_completion(result) -``` - -### Set up the agent with Arcade tools - -Create an agent and provide it with the Arcade tools: - -```python -# import the Google ADK requirements -from google.adk import Agent, Runner -from google.adk.artifacts import InMemoryArtifactService -from google.adk.sessions import InMemorySessionService -from google.genai import types - -# create a new session and artifact services -session_service = InMemorySessionService() -artifact_service = InMemoryArtifactService() - -# Create an agent with Gmail tools -google_agent = Agent( - model="gemini-2.0-flash", - name="google_tool_agent", - instruction="I can use Gmail tools to manage an inbox!", - description="An agent equipped with tools to read Gmail emails." - tools=tools, -) -``` - -### Run the agent with user context - -Run the agent, providing a user_id for tool authorization: - -```python -# create a new session and pass the user id into the context -session = await session_service.create_session( - app_name=app_name, user_id=user_id, state={ - "user_id": user_id, - } -) - -# create a new runner with the agent and services -runner = Runner( - app_name=app_name, - agent=google_agent, - artifact_service=artifact_service, - session_service=session_service, -) - -# pass a prompt to the agent and stream the response -user_input = "summarize my latest 3 emails" -content = types.Content( - role='user', parts=[types.Part.from_text(text=user_input)] -) -for event in runner.run( - user_id=user_id, - session_id=session.id, - new_message=content, -): - if event.content.parts and event.content.parts[0].text: - print(f'** {event.author}: {event.content.parts[0].text}') -``` - -### Complete example - -Here's a complete example putting everything together: - -```python -import asyncio - -from arcadepy import AsyncArcade -from google.adk import Agent, Runner -from google.adk.artifacts import InMemoryArtifactService -from google.adk.sessions import InMemorySessionService -from google.genai import types - -from google_adk_arcade.tools import get_arcade_tools - - -async def main(): - app_name = 'my_app' - user_id = 'mateo@arcade.dev' - session_service = InMemorySessionService() - artifact_service = InMemoryArtifactService() - client = AsyncArcade() - - google_tools = await get_arcade_tools(client, tools=["Gmail.ListEmails"]) - - # authorize the tools - for tool in google_tools: - result = await client.tools.authorize( - tool_name=tool.name, - user_id=user_id - ) - if result.status != "completed": - print(f"Click this link to authorize {tool.name}:\n{result.url}") - await client.auth.wait_for_completion(result) - - google_agent = Agent( - model="gemini-2.0-flash", - name="google_tool_agent", - instruction="I can use Gmail tools to manage an inbox!", - description="An agent equipped with tools to read Gmail emails. " - "Make sure to call gmail_listemails to read and summarize" - " emails", - tools=google_tools, - ) - session = await session_service.create_session( - app_name=app_name, user_id=user_id, state={ - "user_id": user_id, - } - ) - runner = Runner( - app_name=app_name, - agent=google_agent, - artifact_service=artifact_service, - session_service=session_service, - ) - - user_input = "summarize my latest 3 emails" - content = types.Content( - role='user', parts=[types.Part.from_text(text=user_input)] - ) - for event in runner.run( - user_id=user_id, - session_id=session.id, - new_message=content, - ): - if event.content.parts and event.content.parts[0].text: - print(f'** {event.author}: {event.content.parts[0].text}') - -if __name__ == '__main__': - asyncio.run(main()) - -``` - - - -## Tips for selecting tools - -- **Relevance**: Pick only the tools you need. Avoid using all tools at once. -- **User identification**: Always provide a unique and consistent `user_id` for each user. Use your internal or database user ID, not something entered by the user. - -## Next steps - -Now that you have integrated Arcade tools into your Google ADK application, you can: - -- Experiment with different MCP Servers, such as "Github" or "LinkedIn" -- Customize the agent's instructions for specific tasks -- Try out multi-agent systems using different Arcade tools -- Build your own custom tools with the Arcade Tool SDK - -Enjoy exploring Arcade and building powerful AI-enabled Python applications! diff --git a/app/en/home/improve-performance/_meta.tsx b/app/en/home/improve-performance/_meta.tsx new file mode 100644 index 000000000..04730e0f9 --- /dev/null +++ b/app/en/home/improve-performance/_meta.tsx @@ -0,0 +1,7 @@ +export default { + "types-of-tools": "Types of tools", + "eval-starter-tools": "Write eval to assess combo of starter tools", + "custom-tool-improvements": + "Write custom tool that improves on relevant Starter tools", + "run-evaluations-2": "Run evaluations", +}; diff --git a/app/en/home/improve-performance/custom-tool-improvements/page.mdx b/app/en/home/improve-performance/custom-tool-improvements/page.mdx new file mode 100644 index 000000000..5ec9cca20 --- /dev/null +++ b/app/en/home/improve-performance/custom-tool-improvements/page.mdx @@ -0,0 +1,7 @@ +# custom-tool-improvements + +Documentation coming soon. + +## Overview + +This section will contain detailed information about custom-tool-improvements. diff --git a/app/en/home/improve-performance/eval-starter-tools/page.mdx b/app/en/home/improve-performance/eval-starter-tools/page.mdx new file mode 100644 index 000000000..4df143348 --- /dev/null +++ b/app/en/home/improve-performance/eval-starter-tools/page.mdx @@ -0,0 +1,7 @@ +# eval-starter-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about eval-starter-tools. diff --git a/app/en/home/improve-performance/run-evaluations-2/page.mdx b/app/en/home/improve-performance/run-evaluations-2/page.mdx new file mode 100644 index 000000000..e3b7f1ae0 --- /dev/null +++ b/app/en/home/improve-performance/run-evaluations-2/page.mdx @@ -0,0 +1,7 @@ +# run-evaluations-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-evaluations-2. diff --git a/app/en/home/improve-performance/types-of-tools/page.mdx b/app/en/home/improve-performance/types-of-tools/page.mdx new file mode 100644 index 000000000..f444c3598 --- /dev/null +++ b/app/en/home/improve-performance/types-of-tools/page.mdx @@ -0,0 +1,7 @@ +# types-of-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about types-of-tools. diff --git a/app/en/home/langchain/_meta.tsx b/app/en/home/langchain/_meta.tsx index a2708a562..fb7cc7bbc 100644 --- a/app/en/home/langchain/_meta.tsx +++ b/app/en/home/langchain/_meta.tsx @@ -1,5 +1,5 @@ export default { - "use-arcade-tools": "Using Arcade tools", - "user-auth-interrupts": "User authorization", - "auth-langchain-tools": "Authorizing existing tools", + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", + "using-langgraph-tools": "Using LangGraph tools", }; diff --git a/app/en/home/langchain/auth-langchain-tools/page.mdx b/app/en/home/langchain/auth-langchain-tools/page.mdx deleted file mode 100644 index 5107888db..000000000 --- a/app/en/home/langchain/auth-langchain-tools/page.mdx +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: "Authorize Existing Tools" -description: "Use Arcade to authorize existing tools" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -## Authorize Existing Tools - -In this guide, we'll show you how to authorize LangChain tools like the `GmailToolkit` using Arcade. You may already have tools you want to use, and this guide will show you how to authorize them. Arcade handles retrieving, authorizing, and managing tokens so you don't have to. For complete working examples, see our [Python](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain/langchain_tool_arcade_auth.py) and [JavaScript](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain-ts/langchain-tool-arcade-auth.ts) examples. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Install the required packages - -Instead of the `langchain_arcade` package, you only need the `arcadepy` package to authorize existing tools since Arcade tools are not being used. - - - -```bash -pip install langchain-openai langgraph arcadepy langchain-google-community -``` - - -```bash -npm install @arcadeai/arcadejs @langchain/openai @langchain/core @langchain/langgraph @langchain/community -``` - - -### Import the necessary packages - - - -```python -import os -from arcadepy import Arcade -from google.oauth2.credentials import Credentials -from langchain_google_community import GmailToolkit -from langchain_google_community.gmail.utils import build_resource_service -from langchain_openai import ChatOpenAI -from langgraph.prebuilt import create_react_agent -``` - - -```javascript -import { Arcade } from "@arcadeai/arcadejs"; -import { - GmailCreateDraft, - GmailGetMessage, - GmailGetThread, - GmailSearch, - GmailSendMessage, -} from "@langchain/community/tools/gmail"; -import type { StructuredTool } from "@langchain/core/tools"; -import { createReactAgent } from "@langchain/langgraph/prebuilt"; -import { ChatOpenAI } from "@langchain/openai"; -``` - - -### Initialize the Arcade client - - - -```python -api_key = os.getenv("ARCADE_API_KEY") -client = Arcade(api_key=api_key) -``` - - -```javascript -const arcade = new Arcade(); -``` - - - -### Start the authorization process for Gmail - - - -```python -user_id = "{arcade_user_id}" -auth_response = client.auth.start( - user_id=user_id, - provider="google", - scopes=["https://www.googleapis.com/auth/gmail.readonly"], -) -``` - - -```javascript -const USER_ID = "{arcade_user_id}"; -const authResponse = await arcade.auth.start(USER_ID, "google", { - scopes: ["https://www.googleapis.com/auth/gmail.readonly"], -}); - -``` - - - -### Prompt the user to authorize - - - -```python -if auth_response.status != "completed": - print("Please authorize the application in your browser:") - print(auth_response.url) -``` - -The `auth_response.status` will be `"completed"` if the user has already authorized the application, so they won't be prompted to authorize again. - - -```javascript -if (authResponse.status !== "completed") { - console.log("Please authorize the application in your browser:"); - console.log(authResponse.url); -} -``` - -The `authResponse.status` will be `"completed"` if the user has already authorized the application, so they won't be prompted to authorize again. - - - - -### Wait for authorization completion - - - -```python -auth_response = client.auth.wait_for_completion(auth_response) -``` - -The `wait_for_completion` method will do nothing if the user has already authorized the application. - - -```javascript -const completedAuth = await arcade.auth.waitForCompletion(authResponse); -``` - -The `waitForCompletion` method will do nothing if the user has already authorized the application. - - - - -### Use the token to initialize the Gmail MCP Server - - - -```python -creds = Credentials(auth_response.context.token) -api_resource = build_resource_service(credentials=creds) -toolkit = GmailToolkit(api_resource=api_resource) -tools = toolkit.get_tools() -``` - - -```javascript -const gmailParam = { - credentials: { - accessToken: completedAuth.context.token, - }, -}; -const tools: StructuredTool[] = [ - new GmailCreateDraft(gmailParam), - new GmailGetMessage(gmailParam), - new GmailGetThread(gmailParam), - new GmailSearch(gmailParam), - new GmailSendMessage(gmailParam), -]; -``` - - -### Initialize the agent - - - -```python -model = ChatOpenAI(model="gpt-4o") -agent_executor = create_react_agent(model, tools) -``` - - -```javascript -const llm = new ChatOpenAI({ model: "gpt-4o" }); -const agent_executor = createReactAgent({ llm, tools }); -``` - - -### Execute the agent - - - -```python -example_query = "Read my latest emails and summarize them." - -events = agent_executor.stream( - {"messages": [("user", example_query)]}, - stream_mode="values", -) -for event in events: - event["messages"][-1].pretty_print() -``` - - -```javascript -const exampleQuery = "Read my latest emails and summarize them."; -const events = await agent_executor.stream({ messages: [ { role: "user", content: exampleQuery } ] }, { streamMode: "values" } ); -for await (const event of events) { - console.log(event.messages[event.messages.length - 1]); -} -``` - - - - -### Next Steps - -Now you're ready to explore more LangChain tools with Arcade. Try integrating additional MCP Servers and crafting more complex queries to enhance your AI workflows. diff --git a/app/en/home/langchain/quickstart-python/page.mdx b/app/en/home/langchain/quickstart-python/page.mdx new file mode 100644 index 000000000..e3c23b656 --- /dev/null +++ b/app/en/home/langchain/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph with Python. \ No newline at end of file diff --git a/app/en/home/langchain/quickstart-typescript/page.mdx b/app/en/home/langchain/quickstart-typescript/page.mdx new file mode 100644 index 000000000..103d4694d --- /dev/null +++ b/app/en/home/langchain/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph with TypeScript. \ No newline at end of file diff --git a/app/en/home/langchain/use-arcade-tools/page.mdx b/app/en/home/langchain/use-arcade-tools/page.mdx deleted file mode 100644 index 1ff3964c9..000000000 --- a/app/en/home/langchain/use-arcade-tools/page.mdx +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: "Use Arcade tools with LangGraph" -description: "Integrate Arcade tools into your LangGraph applications" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -## Use LangGraph with Arcade - -In this guide, let's explore how to integrate Arcade tools into your LangGraph application. Follow the step-by-step instructions below. For complete working examples, see our [Python](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain/langgraph_arcade_minimal.py) and [JavaScript](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain-ts/langgraph-arcade-minimal.ts) examples. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Set up your environment - -Install the required packages, and ensure your environment variables are set with your Arcade and OpenAI API keys: - - - -```bash -pip install langchain-arcade langchain-openai langgraph -``` - - -```bash -npm install @arcadeai/arcadejs @langchain/openai @langchain/core @langchain/langgraph -``` - - - - -### Configure API keys - -Provide your Arcade and OpenAI API keys. You can store them in environment variables or directly in your code: - -> Need an Arcade API key? Visit the [Get an API key](/home/api-keys) page to create one. - - - -```python -import os - -arcade_api_key = os.environ.get("ARCADE_API_KEY", "YOUR_ARCADE_API_KEY") -openai_api_key = os.environ.get("OPENAI_API_KEY", "YOUR_OPENAI_API_KEY") -``` - - -```bash -ARCADE_API_KEY= -OPENAI_API_KEY= -``` - - - -### Create and manage Arcade tools - - - -Use the ArcadeToolManager to retrieve specific tools or entire MCP Servers: - -```python -from langchain_arcade import ArcadeToolManager - -manager = ArcadeToolManager(api_key=arcade_api_key) - -# Fetch the "ScrapeUrl" tool from the "Firecrawl" MCP Server -tools = manager.get_tools(tools=["Firecrawl.ScrapeUrl"]) -print(manager.tools) - -# Get all tools from the "Gmail" MCP Server -tools = manager.get_tools(toolkits=["Gmail"]) -print(manager.tools) -``` - - -Arcade offers methods to convert tools into Zod schemas, which is essential since LangGraph defines tools using Zod. The `toZod` method is particularly useful, as it simplifies this integration and makes it easier to use Arcade's tools with LangGraph. Learn more about Arcade's Zod integration options [here](/home/use-tools/get-tool-definitions#get-zod-tool-definitions). -```javascript -import { Arcade } from "@arcadeai/arcadejs"; -import { executeOrAuthorizeZodTool, toZod } from "@arcadeai/arcadejs/lib"; -import { tool } from "@langchain/core/tools"; - -// Initialize the Arcade client -const arcade = new Arcade(); - -// Get the Arcade tools, you can customize the MCP Server (e.g. "github", "notion", "gmail", etc.) -const googleToolkit = await arcade.tools.list({ toolkit: "gmail", limit: 30 }); -const arcadeTools = toZod({ - tools: googleToolkit.items, - client: arcade, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) -}); -// Convert Arcade tools to LangGraph tools -const tools = arcadeTools.map(({ name, description, execute, parameters }) => - tool(execute, { - name, - description, - schema: parameters, - }), -); -console.log(tools); -``` - - - - -### Set up the language model and memory - -Create an AI model and bind your tools. Use MemorySaver for checkpointing: - - - -```python -from langchain_openai import ChatOpenAI -from langgraph.checkpoint.memory import MemorySaver - -model = ChatOpenAI(model="gpt-4o", api_key=openai_api_key) -bound_model = model.bind_tools(tools) - -memory = MemorySaver() -``` - - -```javascript -import { ChatOpenAI } from "@langchain/openai"; -import { MemorySaver } from "@langchain/langgraph"; - -const model = new ChatOpenAI({ model: "gpt-4o", apiKey: process.env.OPENAI_API_KEY }); -const boundModel = model.bindTools(tools); -const memory = new MemorySaver(); -``` - - - -### Create a ReAct-style agent - -Use the prebuilt ReAct agent from LangGraph to handle your Arcade tools: - - -```python -from langgraph.prebuilt import create_react_agent - -graph = create_react_agent(model=bound_model, tools=tools, checkpointer=memory) -``` - - -```javascript -import { createReactAgent } from "@langchain/langgraph/prebuilt"; - -const graph = createReactAgent({ llm: boundModel, tools, checkpointer: memory }); -``` - - - -### Provide configuration and user query - -Supply a basic config dictionary and a user query. Notice that user_id is required for tool authorization: - - -```python -config = { - "configurable": { - "thread_id": "1", - "user_id": "{arcade_user_id}" - } -} -user_input = { - "messages": [ - ("user", "List any new and important emails in my inbox.") - ] -} -``` - - -```javascript -const config = { - configurable: { - thread_id: "1", - user_id: "{arcade_user_id}", - }, - streamMode: "values" as const, -}; -const user_input = { - messages: [ - { - role: "user", - content: "List any new and important emails in my inbox.", - }, - ], -}; -``` - - - -### Stream the response - -Stream the assistant's output. If the tool requires authorization, the agent will ask the user to authorize the tool. - - - -```python -from langgraph.errors import NodeInterrupt - -try: - for chunk in graph.stream(user_input, config, stream_mode="values"): - chunk["messages"][-1].pretty_print() -except NodeInterrupt as exc: - print(f"\nNodeInterrupt occurred: {exc}") - print("Please authorize the tool or update the request, then re-run.") -``` - - -```javascript -try { - const stream = await graph.stream(user_input, config); - for await (const chunk of stream) { - console.log(chunk.messages[chunk.messages.length - 1]); - } -} catch (error) { - console.error("Error streaming response:", error); -} -``` - - - - -## Tips for selecting tools - -- **Relevance**: Pick only the tools you need. Avoid using all tools at once. -- **Avoid conflicts**: Be mindful of duplicate or overlapping functionality. - -## Next steps - -Now that you have integrated Arcade tools into your LangGraph agent, you can: - -- Experiment with different MCP Servers, such as "Math" or "Search." -- Customize the agent's prompts for specific tasks. -- Try out other language models and compare their performance. - -Enjoy exploring Arcade and building powerful AI-enabled Python applications! diff --git a/app/en/home/langchain/user-auth-interrupts/page.mdx b/app/en/home/langchain/user-auth-interrupts/page.mdx deleted file mode 100644 index b03a57735..000000000 --- a/app/en/home/langchain/user-auth-interrupts/page.mdx +++ /dev/null @@ -1,373 +0,0 @@ ---- -title: "Using Arcade User Auth" -description: "Build a custom LangGraph that handles tool authorization with Arcade" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -## User Authorization in LangGraph - -In this guide, you will create a LangGraph workflow that requires user authorization before running certain Arcade tools. When a tool needs authorization, the graph displays an authorization URL and waits for the user's approval. This ensures that only the tools you explicitly authorize are available to the language model. For complete working examples, see our [Python](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain/langgraph_with_user_auth.py) and [JavaScript](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/langchain-ts/langgraph-with-user-auth.ts) examples. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Install the required packages - -Set up your environment with the following installations: - - - -```bash -pip install langchain-arcade langchain-openai langgraph -``` - - -```bash -npm install @arcadeai/arcadejs @langchain/openai @langchain/core @langchain/langgraph -``` - - - -### Configure your Arcade environment - -Make sure you have set your Arcade API key (and any other relevant keys) in the environment, or assign them directly in the code: - -> Need an Arcade API key? Visit the [Get an API key](/home/api-keys) page to create one. - - - -```python -import os - -# Import necessary classes and modules -from langchain_arcade import ArcadeToolManager -from langchain_openai import ChatOpenAI -from langgraph.checkpoint.memory import MemorySaver -from langgraph.graph import END, START, MessagesState, StateGraph -from langgraph.prebuilt import ToolNode -from langchain_core.runnables import RunnableConfig - -arcade_api_key = os.environ["ARCADE_API_KEY"] - -# Initialize the tool manager and fetch tools compatible with langgraph -tool_manager = ArcadeToolManager(api_key=arcade_api_key) -tools = tool_manager.get_tools(toolkits=["Gmail"]) -tool_node = ToolNode(tools) - -# Create a language model instance and bind it with the tools -model = ChatOpenAI(model="gpt-4o") -model_with_tools = model.bind_tools(tools) -``` - -Here are the main code elements: - -- arcade_api_key is your Arcade key. -- tool_manager fetches your Arcade tools, for example the "Gmail" MCP Server. -- tool_node encapsulates these tools for usage in LangGraph. -- model_with_tools binds your tools to the "gpt-4o" language model, enabling tool calls. - - - -```javascript -import { pathToFileURL } from "node:url"; -import { Arcade } from "@arcadeai/arcadejs"; -import { toZod } from "@arcadeai/arcadejs/lib"; -import type { AIMessage } from "@langchain/core/messages"; -import { tool } from "@langchain/core/tools"; -import { MessagesAnnotation, StateGraph } from "@langchain/langgraph"; -import { ToolNode } from "@langchain/langgraph/prebuilt"; -import { ChatOpenAI } from "@langchain/openai"; - -// Initialize Arcade with API key from environment -const arcade = new Arcade(); - -// Replace with your application's user ID (e.g. email address, UUID, etc.) -const USER_ID = "{arcade_user_id}"; - -// Initialize tools from Gmail MCP Server -const googleToolkit = await arcade.tools.list({ toolkit: "gmail", limit: 30 }); -const arcadeTools = toZod({ - tools: googleToolkit.items, - client: arcade, - userId: USER_ID, -}); - -// Convert Arcade tools to LangGraph tools -const tools = arcadeTools.map(({ name, description, execute, parameters }) => - tool(execute, { - name, - description, - schema: parameters, - }), -); - -// Initialize the prebuilt tool node -const toolNode = new ToolNode(tools); - -// Create a language model instance and bind it with the tools -const model = new ChatOpenAI({ - model: "gpt-4o", - apiKey: process.env.OPENAI_API_KEY, -}); -const modelWithTools = model.bindTools(tools); -``` - -Here are the main code elements: - -- arcade.tools.list fetches your Arcade tools, for example the "Gmail" MCP Server. -- toZod converts Arcade tools to Zod schemas, which are required by LangGraph. -- ToolNode encapsulates these tools for usage in LangGraph. -- modelWithTools binds your tools to the "gpt-4o" language model, enabling tool calls. - - - - -### Define the workflow steps - -You will create three primary functions to handle AI interaction, tool authorization, and flow control. - - -```python -# Function to invoke the model and get a response -def call_agent(state: MessagesState): - messages = state["messages"] - response = model_with_tools.invoke(messages) - # Return the updated message history - return {"messages": [response]} - - -# Function to determine the next step in the workflow based on the last message -def should_continue(state: MessagesState): - if state["messages"][-1].tool_calls: - for tool_call in state["messages"][-1].tool_calls: - if tool_manager.requires_auth(tool_call["name"]): - return "authorization" - return "tools" # Proceed to tool execution if no authorization is needed - return END # End the workflow if no tool calls are present - - -# Function to handle authorization for tools that require it -def authorize(state: MessagesState, config: RunnableConfig | None = None): - if config is None: - raise ValueError("Config is required for authorization") - - user_id = config["configurable"].get("user_id") - for tool_call in state["messages"][-1].tool_calls: - tool_name = tool_call["name"] - if not tool_manager.requires_auth(tool_name): - continue - auth_response = tool_manager.authorize(tool_name, user_id) - if auth_response.status != "completed": - # Prompt the user to visit the authorization URL - print(f"Visit the following URL to authorize: {auth_response.url}") - - # Wait for the user to complete the authorization - # and then check the authorization status again - tool_manager.wait_for_auth(auth_response.id) - if not tool_manager.is_authorized(auth_response.id): - # This stops execution if authorization fails - raise ValueError("Authorization failed.") - - return {"messages": []} -``` -Explanations for these functions: - -- call_agent: Invokes the language model using the latest conversation state. -- should_continue: Checks the last AI message for any tool calls. If a tool requires authorization, the flow transitions to authorization. Otherwise, it goes straight to tool execution or ends if no tools are called. -- authorize: Prompts the user to authorize any required tools, blocking until authorization is completed successfully or fails. - - -```javascript -// Function to check if a tool requires authorization -async function requiresAuth(toolName: string): Promise<{ - needsAuth: boolean; - id: string; - authUrl: string; -}> { - const authResponse = await arcade.tools.authorize({ - tool_name: toolName, - user_id: USER_ID, - }); - return { - needsAuth: authResponse.status === "pending", - id: authResponse.id ?? "", - authUrl: authResponse.url ?? "", - }; -} - -// Function to invoke the model and get a response -async function callAgent( - state: typeof MessagesAnnotation.State, -): Promise { - const messages = state.messages; - const response = await modelWithTools.invoke(messages); - return { messages: [response] }; -} - -// Function to determine the next step in the workflow based on the last message -async function shouldContinue( - state: typeof MessagesAnnotation.State, -): Promise { - const lastMessage = state.messages[state.messages.length - 1] as AIMessage; - if (lastMessage.tool_calls?.length) { - for (const toolCall of lastMessage.tool_calls) { - const { needsAuth } = await requiresAuth(toolCall.name); - if (needsAuth) { - return "authorization"; - } - } - return "tools"; // Proceed to tool execution if no authorization is needed - } - return "__end__"; // End the workflow if no tool calls are present -} - -// Function to handle authorization for tools that require it -async function authorize( - state: typeof MessagesAnnotation.State, -): Promise { - const lastMessage = state.messages[state.messages.length - 1] as AIMessage; - for (const toolCall of lastMessage.tool_calls || []) { - const toolName = toolCall.name; - const { needsAuth, id, authUrl } = await requiresAuth(toolName); - if (needsAuth) { - // Prompt the user to visit the authorization URL - console.log(`Visit the following URL to authorize: ${authUrl}`); - - // Wait for the user to complete the authorization - const response = await arcade.auth.waitForCompletion(id); - if (response.status !== "completed") { - throw new Error("Authorization failed"); - } - } - } - - return { messages: [] }; -} -``` - -Explanations for these functions: - -- requiresAuth: Checks if a tool requires authorization. -- callAgent: Invokes the language model using the latest conversation state. -- shouldContinue: Checks the last AI message for any tool calls. If a tool requires authorization, the flow transitions to authorization. Otherwise, it goes straight to tool execution or ends if no tools are called. -- authorize: Prompts the user to authorize any required tools, blocking until authorization is completed successfully or fails. - - - - -### Build and compile your LangGraph workflow - -Use StateGraph to assemble the nodes and edges, then compile the graph with a MemorySaver. - - - -```python -if __name__ == "__main__": - # Build the workflow graph using StateGraph - workflow = StateGraph(MessagesState) - - # Add nodes (steps) to the graph - workflow.add_node("agent", call_agent) - workflow.add_node("tools", tool_node) - workflow.add_node("authorization", authorize) - - # Define the edges and control flow between nodes - workflow.add_edge(START, "agent") - workflow.add_conditional_edges("agent", should_continue, ["authorization", "tools", END]) - workflow.add_edge("authorization", "tools") - workflow.add_edge("tools", "agent") - - # Set up memory for checkpointing the state - memory = MemorySaver() - - # Compile the graph with the checkpointer - graph = workflow.compile(checkpointer=memory) -``` - - -```javascript -// Build the workflow graph -const workflow = new StateGraph(MessagesAnnotation) - .addNode("agent", callAgent) - .addNode("tools", toolNode) - .addNode("authorization", authorize) - .addEdge("__start__", "agent") - .addConditionalEdges("agent", shouldContinue, [ - "authorization", - "tools", - "__end__", - ]) - .addEdge("authorization", "tools") - .addEdge("tools", "agent"); - -// Compile the graph -const graph = workflow.compile(); -``` - - - -### Provide inputs and run the graph - -Finally, define user-supplied messages, authorization config, and stream the outputs. The graph will pause for any required tool authorization. - - - -```python -# Define the input messages from the user -inputs = { - "messages": [ - { - "role": "user", - "content": "Check and see if I have any emails in my inbox", - } - ], -} - -# Configuration with thread and user IDs for authorization purposes -config = {"configurable": {"thread_id": "4", "user_id": "{arcade_user_id}"}} - -# Run the graph and stream the outputs -for chunk in graph.stream(inputs, config=config, stream_mode="values"): - # Pretty-print the last message in the chunk - chunk["messages"][-1].pretty_print() -``` - - -```javascript -const inputs = { - messages: [ - { - role: "user", - content: "Check and see if I have any important emails in my inbox", - }, - ], -}; -// Run the graph and stream the outputs -const stream = await graph.stream(inputs, { streamMode: "values" }); -for await (const chunk of stream) { - // Print the last message in the chunk - console.log(chunk.messages[chunk.messages.length - 1].content); -} -``` - - - -In this example: - -- The user prompts the agent to check emails. -- The message triggers a potential need for the "Gmail" MCP Server. -- If authorization is required, the code prints a URL and waits until you permit the tool call. - - - -## Next steps - -- Experiment with more Arcade MCP Servers for expanded capabilities. -- Explore advanced authorization logic, such as multi-user or role-based checks. -- Integrate additional nodes to handle more complex flows or multi-step tasks in your LangGraph. - -By combining Arcade's authorization features with stateful management in LangGraph, you can build AI-driven workflows that respect user permissions at every step. Have fun exploring Arcade! diff --git a/app/en/home/langchain/using-langgraph-tools/page.mdx b/app/en/home/langchain/using-langgraph-tools/page.mdx new file mode 100644 index 000000000..0bdf9a500 --- /dev/null +++ b/app/en/home/langchain/using-langgraph-tools/page.mdx @@ -0,0 +1,7 @@ +# Using LangGraph tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph tools. \ No newline at end of file diff --git a/app/en/home/mastra/_meta.tsx b/app/en/home/mastra/_meta.tsx index 9c7bbf1eb..5df9193ec 100644 --- a/app/en/home/mastra/_meta.tsx +++ b/app/en/home/mastra/_meta.tsx @@ -8,14 +8,8 @@ const meta: MetaRecord = { copyPage: true, }, }, - overview: { - title: "Overview", - }, - "use-arcade-tools": { - title: "Using Arcade tools", - }, - "user-auth-interrupts": { - title: "Managing user authorization", + "quickstart-typescript": { + title: "Quickstart (Typescript)", }, }; diff --git a/app/en/home/mastra/overview/page.mdx b/app/en/home/mastra/overview/page.mdx deleted file mode 100644 index e61b3f3c5..000000000 --- a/app/en/home/mastra/overview/page.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: "Integrating Arcade with Mastra" -description: "Leverage Arcade's tool ecosystem within your Mastra applications." ---- - -import { Callout } from "nextra/components"; - -## Overview: Arcade Tools in Mastra - -[Mastra](https://mastra.ai/docs) is an open-source TypeScript agent framework that provides essential primitives for building AI applications. Integrate Arcade's extensive tool ecosystem to enhance your Mastra agents and enable them to interact seamlessly with numerous third-party services. - -This integration enables you to: - -- **Access a wide range of tools:** Use Arcade's [pre-built tools](/mcp-servers) for GitHub, Google Workspace, Slack, and more directly within your Mastra agent. -- **Simplify tool management:** Let Arcade handle the complexities of tool discovery, execution, and authentication. -- **Build sophisticated agents:** Combine Mastra's agent framework (including memory, workflows, and RAG) with Arcade's powerful tool capabilities. - -### How it Works - -The integration works through three key mechanisms: - -1. **Tool Discovery:** Access available tools through a unified API (`arcade.tools.list`). -2. **Schema Conversion:** Transform Arcade's tool definitions into Mastra-compatible Zod schemas with the `toZodToolSet` utility, enabling seamless integration between the two frameworks without manual schema mapping. -3. **Execution Delegation:** Seamlessly route tool calls from your Mastra agent through Arcade's API, which handles all the complexities of third-party service authentication and execution. - - - Before starting, obtain an [Arcade API key](/home/api-keys). - - -### Next Steps - -- Learn how to [use Arcade tools](/home/mastra/use-arcade-tools) in a Mastra agent -- Implement [user authentication handling](/home/mastra/user-auth-interrupts) for tools in multi-user applications diff --git a/app/en/home/mastra/quickstart-typescript/page.mdx b/app/en/home/mastra/quickstart-typescript/page.mdx new file mode 100644 index 000000000..4d05ea8f5 --- /dev/null +++ b/app/en/home/mastra/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Mastra with TypeScript. \ No newline at end of file diff --git a/app/en/home/mastra/use-arcade-tools/page.mdx b/app/en/home/mastra/use-arcade-tools/page.mdx deleted file mode 100644 index 1e7b0919f..000000000 --- a/app/en/home/mastra/use-arcade-tools/page.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "Using Arcade tools with Mastra" -description: "Integrate Arcade tools into your Mastra applications for basic use cases." ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -This guide shows you how to integrate and use Arcade tools within a Mastra agent. For the complete working example, check out our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/mastra). - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) -- Basic familiarity with TypeScript and Mastra concepts - -### Create a Mastra project - -Start by creating a new Mastra project using the official CLI: - -```bash -# Create a new Mastra project -npx create-mastra@latest my-arcade-agent - -# Navigate to the project -cd my-arcade-agent -``` - -For more details on setting up a Mastra project, refer to the [Mastra documentation](https://mastra.ai/docs/getting-started/installation). - -### Install Arcade client - -Install the Arcade client: - - - - - -```bash -pnpm add @arcadeai/arcadejs -``` - - - - - -```bash -npm install @arcadeai/arcadejs -``` - - - - - -```bash -yarn install @arcadeai/arcadejs -``` - - - - - -### Configure API keys - -Set up your environment with the required API keys: - -```typescript -// Set your API keys in your environment variables or .env file -process.env.ARCADE_API_KEY = "your_arcade_api_key"; -process.env.ANTHROPIC_API_KEY = "your_anthropic_api_key"; // or another supported model provider -``` - -### Convert Arcade tools to Mastra tools - -Arcade offers methods to convert tools into Zod schemas, which is essential since Mastra defines tools using Zod. The `toZodToolSet` method is particularly useful, as it simplifies this integration and makes it easier to use Arcade's tools with Mastra. Learn more about Arcade's Zod integration options [here](/home/use-tools/get-tool-definitions#get-zod-tool-definitions). - -```ts -import { Arcade } from "@arcadeai/arcadejs"; -import { - executeOrAuthorizeZodTool, - toZodToolSet, -} from "@arcadeai/arcadejs/lib"; - -// Initialize Arcade -const arcade = new Arcade(); - -// Get Gmail MCP Server -// MCP Server names can be found in the Arcade dashboard via Tools > view > MCP Server or via the CLI `arcade workers list` -const gmailToolkit = await arcade.tools.list({ toolkit: "Gmail", limit: 30 }); - -// Get Gmail tools -export const gmailTools = toZodToolSet({ - tools: gmailToolkit.items, - client: arcade, - userId: "", // Your app's internal ID for the user (an email, UUID, etc). It's used internally to identify your user in Arcade - executeFactory: executeOrAuthorizeZodTool, // Checks if tool is authorized and executes it, or returns authorization URL if needed -}); - -``` - -### Create and configure your Mastra agent - -Now create a Mastra agent that uses Arcade tools: - -```typescript -import { Agent } from "@mastra/core/agent"; -import { anthropic } from "@ai-sdk/anthropic"; - -// Create the Mastra agent with Arcade tools -export const gmailAgent = new Agent({ - name: "gmailAgent", - instructions: `You are a Gmail assistant that helps users manage their inbox. - -When helping users: -- Always verify their intent before performing actions -- Keep responses clear and concise -- Confirm important actions before executing them -- Respect user privacy and data security - -Use the gmailTools to interact with various Gmail services and perform related tasks.`, - model: anthropic("claude-3-7-sonnet-20250219"), - tools: gmailTools, -}); -``` - -### Interact with your agent - -You can interact with your agent in two main ways: - -**1. Using the Mastra Development Playground:** - -Start the Mastra development server: - -```bash -npm run dev -``` - -This will launch a local development playground, typically accessible at `http://localhost:4111`. Open this URL in your browser, select the `gmailAgent` from the list of available agents, and start chatting with it directly in the UI. - -**2. Programmatically:** - -Alternatively, you can interact with the agent directly in your code: - -```typescript -// Generate a response from the agent -const response = await gmailAgent.generate( - "Read my last email and summarize it in a few sentences", -); -console.log(response.text); - -// Or stream the response for a more interactive experience -const stream = await gmailAgent.stream("Send an email to dev@arcade.dev with the subject 'Hello from Mastra'"); - -for await (const chunk of stream.textStream) { - process.stdout.write(chunk); -} -``` - - - -When running your agent for the first time with tools that require user consent (like Google or Github), the agent will return an authorization reponse (e.g., `{ authorization_required: true, url: '...', message: '...' }`). Your agent's instructions should guide it to present this URL to the user. After the user visits this URL and grants permissions, the tool can be used successfully. See the [Managing user authorization](/home/mastra/user-auth-interrupts) guide for more details on handling authentication flows. diff --git a/app/en/home/mastra/user-auth-interrupts/page.mdx b/app/en/home/mastra/user-auth-interrupts/page.mdx deleted file mode 100644 index eea1f31dc..000000000 --- a/app/en/home/mastra/user-auth-interrupts/page.mdx +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: "Managing user authorization" -description: "Handle user-specific authorization for Arcade tools in Mastra applications." ---- - -import { Callout } from "nextra/components"; - -## Dynamic Tool Loading with Toolsets - -Mastra lets you dynamically provide tools to an agent at runtime using toolsets. This approach is essential when integrating Arcade tools in web applications where each user needs their own authentication flow. - -### Per-User Tool Authentication in Web Applications - -In web applications serving multiple users, implement user-specific authentication flows with these steps: - -First, set up your Mastra configuration and agents in separate files: - -```typescript -// @/mastra/index.ts -import { Mastra } from "@mastra/core"; -import { githubAgent } from "./agents/githubAgent"; - -// Initialize Mastra -export const mastra = new Mastra({ - agents: { - githubAgent, - }, -}); -``` - -```typescript -// @/mastra/agents/githubAgent.ts -import { Agent } from "@mastra/core/agent"; -import { anthropic } from "@ai-sdk/anthropic"; - -// Create the agent without tools - we'll add them at runtime -export const githubAgent = new Agent({ - name: "githubAgent", - instructions: `You are a GitHub Agent that helps with repository management. - - You can help with tasks like: - - Listing repositories - - Creating and managing issues - - Viewing pull requests - - Managing repository settings - - If a tool requires authorization, you will receive an authorization URL. - When that happens, clearly present this URL to the user and ask them to visit it to grant permissions.`, - model: anthropic("claude-3-7-sonnet-20250219"), - // No tools defined here - will be provided dynamically at runtime -}); -``` - -Then, create an API endpoint that provides tools dynamically: - -```typescript -// app/api/chat/route.ts -import { NextRequest, NextResponse } from "next/server"; -import { mastra } from "@/mastra"; -import { Arcade } from "@arcadeai/arcadejs"; -import { getUserSession } from "@/lib/auth"; // Your authentication handling -import { toZodToolSet } from "@arcadeai/arcadejs/lib"; -import { executeOrAuthorizeZodTool } from "@arcadeai/arcadejs/lib"; - -export async function POST(req: NextRequest) { - // Extract request data - const { messages, threadId } = await req.json(); - - // Authenticate the user - const session = await getUserSession(req); - if (!session) { - return NextResponse.json({ message: "Unauthorized" }, { status: 401 }); - } - - try { - // Get the agent from Mastra - const githubAgent = mastra.getAgent("githubAgent"); - - const arcade = new Arcade(); - const githubToolkit = await arcade.tools.list({ toolkit: "github", limit: 30 }); - - // Fetch user-specific Arcade tools for GitHub - const arcadeTools = toZodToolSet({ - tools: githubToolkit.items, - client: arcade, - userId: session.user.email, - executeFactory: executeOrAuthorizeZodTool, - }); - - // Stream the response with dynamically provided tools - const response = await githubAgent.stream(messages, { - threadId, // Optional: For maintaining conversation context - resourceId: session.user.id, // Optional: For associating memory with user - toolChoice: "auto", - toolsets: { - arcade: arcadeTools, // Provide tools in a named toolset - }, - }); - - // Return streaming response - return response.toDataStreamResponse(); - } catch (error) { - console.error("Error processing GitHub request:", error); - return NextResponse.json( - { message: "Failed to process request" }, - { status: 500 }, - ); - } -} -``` - -This approach provides several benefits: - -- Each user gets their own separate authentication flow with Arcade tools -- A single agent instance works with multiple user-specific toolsets - -The toolsets parameter provides tools only for the current request without modifying the agent's base configuration. This makes it ideal for multi-user applications where each user needs their own secure OAuth flow with Arcade. - -## Handling Tool Authorization - -When a tool requires user authorization, the agent receives a response with: - -```typescript -{ - authorization_required: true, - url: "https://auth.arcade.com/...", - message: "Forward this url to the user for authorization" -} -``` - -Your agent should recognize this pattern and present the URL to the user. To create a better user experience: - -- Display the authorization URL as a clickable link in your UI -- Explain which service needs authorization and why -- Provide a way for users to retry their request after authorization - -## Tips for Selecting Tools - -- **Focus on relevance**: Choose tools that directly support your agent's specific purpose -- **Consider performance**: Some tools may have higher latency than others -- **Handle errors gracefully**: Implement robust error handling for third-party service failures -- **Create clear user flows**: Design intuitive authorization experiences - -## Next Steps - -After integrating Arcade tools into your Mastra agent, you can: - -- Add [memory capabilities](https://mastra.ai/docs/agents/agent-memory) to maintain context between interactions -- Implement [structured workflows](https://mastra.ai/docs/workflows/overview) for complex multi-step operations -- Enhance your agent with [RAG capabilities](https://mastra.ai/docs/rag/overview) for domain-specific knowledge -- Set up [logging and tracing](https://mastra.ai/docs/observability/logging) to monitor performance - -For more detailed information on Mastra's capabilities, visit the [Mastra documentation](https://mastra.ai/docs). diff --git a/app/en/home/mcp-gateways/page.mdx b/app/en/home/mcp-gateways/page.mdx deleted file mode 100644 index 17cd6f869..000000000 --- a/app/en/home/mcp-gateways/page.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "MCP Gateways" -description: "Comprehensive guide to using MCP Gateways" ---- - -# MCP Gateways - -MCP Gateways are a way to connect multiple MCP Servers to your agent, application, or IDE. MCP Gateways allow you to federate the tools from multiple MCP Servers into a single collection for easier management, control, and access. 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 LLM. - -## Configure MCP Gateways - -To configure an MCP Gateway, go to the [MCP Gateways dashboard](https://api.arcade.dev/dashboard/mcp-gateways) and click on the "Create MCP Gateway" button. - -When configuring an MCP Gateway, you can select the tools you want to include in the Gateway from any MCP Servers available to the project: - -![MCP Gateway Configuration](/images/mcp-gateway-configuration.png) - -The options available when configuring an MCP Gateway are: -- **Name**: The name of the MCP Gateway. Informative only. -- **Description**: The description of the MCP Gateway. If set, this information will be returned to the LLM to hint at the purpose of the tools within the MCP Gateway. -- **Slug**: The slug of the MCP Gateway. This is the URL slug that will be used to access the MCP Gateway. It must be unique. -- **Allowed Tools**: If set, only the tools in the MCP Servers that are selected will be available to the MCP Gateway. If left blank, all tools from the MCP Servers available to the project will be available through the MCP Gateway. - -## How to use MCP Gateways - -Any MCP client that supports the Streamable HTTP transport can use an Arcade MCP Gateway. To use an Arcade MCP Gateway, you can use the `https://api.arcade.dev/mcp/` URL in your MCP client. Learn how to use MCP Gateways with: -* [Cursor](/home/mcp-clients/cursor) -* [Claude Desktop](/home/mcp-clients/claude-desktop) -* [Visual Studio Code](/home/mcp-clients/visual-studio-code) diff --git a/app/en/home/new-functionality/_meta.tsx b/app/en/home/new-functionality/_meta.tsx new file mode 100644 index 000000000..d03a8c6b0 --- /dev/null +++ b/app/en/home/new-functionality/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "eval-new-functionality": "Write eval for functionality you want", + "custom-toolkit": "Write custom toolkit", + "arcade-deploy-2": "Arcade Deploy", +}; diff --git a/app/en/home/new-functionality/arcade-deploy-2/page.mdx b/app/en/home/new-functionality/arcade-deploy-2/page.mdx new file mode 100644 index 000000000..984ef098c --- /dev/null +++ b/app/en/home/new-functionality/arcade-deploy-2/page.mdx @@ -0,0 +1,7 @@ +# arcade-deploy-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about arcade-deploy-2. diff --git a/app/en/home/new-functionality/custom-toolkit/page.mdx b/app/en/home/new-functionality/custom-toolkit/page.mdx new file mode 100644 index 000000000..48d796c5a --- /dev/null +++ b/app/en/home/new-functionality/custom-toolkit/page.mdx @@ -0,0 +1,7 @@ +# custom-toolkit + +Documentation coming soon. + +## Overview + +This section will contain detailed information about custom-toolkit. diff --git a/app/en/home/new-functionality/eval-new-functionality/page.mdx b/app/en/home/new-functionality/eval-new-functionality/page.mdx new file mode 100644 index 000000000..7acdc5dcb --- /dev/null +++ b/app/en/home/new-functionality/eval-new-functionality/page.mdx @@ -0,0 +1,7 @@ +# eval-new-functionality + +Documentation coming soon. + +## Overview + +This section will contain detailed information about eval-new-functionality. diff --git a/app/en/home/newest-models/_meta.tsx b/app/en/home/newest-models/_meta.tsx new file mode 100644 index 000000000..0bc71b765 --- /dev/null +++ b/app/en/home/newest-models/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "run-eval-new-model": "Run existing eval and observe outcome with new model", + "modify-tool-new-model": "Modify tool to work well with new model", +}; diff --git a/app/en/home/newest-models/modify-tool-new-model/page.mdx b/app/en/home/newest-models/modify-tool-new-model/page.mdx new file mode 100644 index 000000000..8cfa6e27f --- /dev/null +++ b/app/en/home/newest-models/modify-tool-new-model/page.mdx @@ -0,0 +1,7 @@ +# modify-tool-new-model + +Documentation coming soon. + +## Overview + +This section will contain detailed information about modify-tool-new-model. diff --git a/app/en/home/newest-models/run-eval-new-model/page.mdx b/app/en/home/newest-models/run-eval-new-model/page.mdx new file mode 100644 index 000000000..b29b2853e --- /dev/null +++ b/app/en/home/newest-models/run-eval-new-model/page.mdx @@ -0,0 +1,7 @@ +# run-eval-new-model + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-eval-new-model. diff --git a/app/en/home/oai-agents/_meta.tsx b/app/en/home/oai-agents/_meta.tsx index cdb53979a..e0b5f430e 100644 --- a/app/en/home/oai-agents/_meta.tsx +++ b/app/en/home/oai-agents/_meta.tsx @@ -1,5 +1,4 @@ export default { - overview: "Overview", - "use-arcade-tools": "Using Arcade tools", - "user-auth-interrupts": "Managing user authorization", + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", }; diff --git a/app/en/home/oai-agents/overview/page.mdx b/app/en/home/oai-agents/overview/page.mdx deleted file mode 100644 index 27eaa1f72..000000000 --- a/app/en/home/oai-agents/overview/page.mdx +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: "Arcade with OpenAI Agents overview" -description: "Comprehensive guide to using Arcade with the OpenAI Agents library" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -# Arcade with OpenAI Agents - -Arcade provides seamless integration with the [OpenAI Agents Library](https://github.com/openai/openai-python) and [OpenAI Agents JS](https://openai.github.io/openai-agents-js/), allowing you to enhance your AI agents with powerful tools including Gmail, LinkedIn, GitHub, and many more. This integration is available through the `agents-arcade` package for Python and our [JavaScript client library](https://github.com/ArcadeAI/arcade-js). - -## Installation - -Install the necessary packages to get started: - - - - -```bash -pip install agents-arcade arcadepy -``` - - - - - -```bash -npm install @openai/agents @arcadeai/arcadejs -``` - - - - - -Make sure you have your Arcade API key ready. [Get an API key](/home/api-keys) if you don't already have one. - -## Key features - -- **Easy integration** with the OpenAI Agents framework -- **Access to all Arcade MCP Servers** including Google, GitHub, LinkedIn, X, and more -- **Create custom tools** with the Arcade Tool SDK -- **Manage user authentication** for tools that require it -- **Asynchronous support** compatible with OpenAI's Agent framework - -## Basic usage - -Here's a simple example of using Arcade tools with OpenAI Agents: - - - - -```python -from agents import Agent, Runner -from arcadepy import AsyncArcade -from agents_arcade import get_arcade_tools -from agents_arcade.errors import AuthorizationError - -async def main(): - # Initialize the Arcade client - client = AsyncArcade() - - # Get tools from the "gmail" MCP Server - tools = await get_arcade_tools(client, toolkits=["gmail"]) - - # Create an agent with Gmail tools - google_agent = Agent( - name="Gmail agent", - instructions="You are a helpful assistant that can assist with Gmail API calls.", - model="gpt-4o-mini", - tools=tools, - ) - - try: - # Run the agent with a unique user_id for authorization - result = await Runner.run( - starting_agent=google_agent, - input="What are my latest emails?", - context={"user_id": "{arcade_user_id}"}, - ) - print("Final output:\n\n", result.final_output) - except AuthorizationError as e: - print("Please Login to Google:", e) - -if __name__ == "__main__": - import asyncio - asyncio.run(main()) -``` - - - - - -Check out the complete working example in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts/src/index.ts). - -```javascript -import Arcade from "@arcadeai/arcadejs"; -import { executeOrAuthorizeZodTool, toZod } from "@arcadeai/arcadejs/lib"; -import { Agent, run, tool } from "@openai/agents"; - -// 1) Initialize Arcade client -const client = new Arcade(); - -// 2) Fetch Gmail MCP Server from Arcade and prepare tools for OpenAI Agents -const googleToolkit = await client.tools.list({ toolkit: "gmail", limit: 30 }); -const tools = toZod({ - tools: googleToolkit.items, - client, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) - executeFactory: executeOrAuthorizeZodTool, -}).map(tool); - -// 3) Create a new agent with the Gmail MCP Server -const googleAgent = new Agent({ - name: "Gmail agent", - instructions: - "You are a helpful assistant that can assist with Google API calls.", - model: "gpt-4o-mini", - tools, -}); - -// 4) Run the agent -const result = await run(googleAgent, "What are my latest emails?"); - -// 5) Print the result -console.log(result.finalOutput); -``` - - - - - -## Handling authorization - - - - -When a user needs to authorize access to a tool (like Google or GitHub), the agent will raise an `AuthorizationError` with a URL for the user to visit: - -```python -try: - # Run agent code - # ... -except AuthorizationError as e: - # Display the authorization URL to the user - print(f"Please visit this URL to authorize: {e}") -``` - - - - - -When a user needs to authorize access to a tool (like Google or GitHub), the agent will show a message like this: - -```bash -[Authorize Gmail Access](https://accounts.google.com/o/oauth2/v2/auth?access_type=offline...) -Once you have authorized access, I can retrieve your latest emails. -``` - - - - -After visiting the URL and authorizing access, the user can run the agent again with the same `user_id`, and it will work without requiring re-authorization. - -## Available MCP Servers - -Arcade provides a variety of MCP Servers you can use with your agents: - -- **Google Suite**: Gmail, Calendar, Drive, Docs -- **Social Media**: LinkedIn, X -- **Development**: GitHub -- **Web**: Web search, content extraction -- **And more**: Weather, financial data, etc. - -For a full list of available MCP Servers, visit the [Arcade MCP Servers](/mcp-servers) documentation. - -## Next steps - -Ready to start building with Arcade and OpenAI Agents? Check out these guides: - -- [Using Arcade tools](/home/oai-agents/use-arcade-tools) - Learn the basics of using Arcade tools with OpenAI Agents -- [Managing user authorization](/home/oai-agents/user-auth-interrupts) - Handle tool authorization efficiently -- [Creating custom tools](/home/build-tools/create-a-mcp-server) - Build your own tools with the Arcade Tool SDK - -Enjoy exploring Arcade and building powerful AI-enabled applications! diff --git a/app/en/home/oai-agents/quickstart-python/page.mdx b/app/en/home/oai-agents/quickstart-python/page.mdx new file mode 100644 index 000000000..2c7ba7b17 --- /dev/null +++ b/app/en/home/oai-agents/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAI Agents with Python. \ No newline at end of file diff --git a/app/en/home/oai-agents/quickstart-typescript/page.mdx b/app/en/home/oai-agents/quickstart-typescript/page.mdx new file mode 100644 index 000000000..17a8cd8f1 --- /dev/null +++ b/app/en/home/oai-agents/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAI Agents with TypeScript. \ No newline at end of file diff --git a/app/en/home/oai-agents/use-arcade-tools/page.mdx b/app/en/home/oai-agents/use-arcade-tools/page.mdx deleted file mode 100644 index 0b098f28c..000000000 --- a/app/en/home/oai-agents/use-arcade-tools/page.mdx +++ /dev/null @@ -1,346 +0,0 @@ ---- -title: "Use Arcade with OpenAI Agents" -description: "Integrate Arcade tools into your OpenAI Agents applications" ---- -import { Steps, Tabs, Callout } from "nextra/components"; - -## Use Arcade with OpenAI Agents - -In this guide, let's explore how to integrate Arcade tools into your OpenAI Agents application. Follow the step-by-step instructions below. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Set up your environment - -Install the required packages, and ensure your environment variables are set with your Arcade API key: - - - - - -```bash -pip install agents-arcade arcadepy -``` - - - - - -```bash -npm install @openai/agents @arcadeai/arcadejs -``` - - - - - -### Configure API keys - -Provide your Arcade API key. You can store it in environment variables or directly in your code: - -> Need an Arcade API key? Visit the [Get an API key](/home/api-keys) page to create one. - - - - -```python -import os - -os.environ["ARCADE_API_KEY"] = "YOUR_ARCADE_API_KEY" -# Or set it directly when initializing the client -``` - - - - - -```bash -# In your .env file -ARCADE_API_KEY=YOUR_ARCADE_API_KEY -``` - - - - - - - -### Create and manage Arcade tools - - - - -Use the `get_arcade_tools` function to retrieve tools from specific MCP Servers: - -```python -from arcadepy import AsyncArcade -from agents_arcade import get_arcade_tools - -# Initialize the Arcade client -client = AsyncArcade() - -# Get all tools from the "Gmail" MCP Server -tools = await get_arcade_tools(client, toolkits=["gmail"]) - -# You can request multiple MCP Servers at once -tools = await get_arcade_tools(client, toolkits=["gmail", "github", "linkedin"]) - -# You can request specific tools -tools = await get_arcade_tools(client, tools=["Gmail_ListEmails", "Slack_ListUsers", "Slack_SendDmToUser"]) -``` - - - - - -```javascript -import Arcade from '@arcadeai/arcadejs'; -import { executeOrAuthorizeZodTool, toZod } from "@arcadeai/arcadejs/lib"; -import { tool } from '@openai/agents'; - -const client = new Arcade(); - -// Option 1: Get tools from a single MCP Server -const googleTools = await client.tools.list({ toolkit: "gmail", limit: 30 }); -const toolsFromGoogle = googleTools.items; - -// Option 2: Get tools from multiple MCP Servers -const [google, github, linkedin] = await Promise.all([ - client.tools.list({ toolkit: "gmail", limit: 30 }), - client.tools.list({ toolkit: "github", limit: 30 }), - client.tools.list({ toolkit: "linkedin", limit: 30 }) -]); -const toolsFromMultiple = [...google.items, ...github.items, ...linkedin.items]; - -// Option 3: Get specific tools by name -const specificTools = await Promise.all([ - client.tools.get("Gmail_ListEmails"), - client.tools.get("Slack_ListUsers"), - client.tools.get("Slack_SendDmToUser"), -]); - -// Convert any of the above to OpenAI Agents format -const convertToAgents = (arcadeTools) => { - return toZod({ - tools: arcadeTools, - client, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) - executeFactory: executeOrAuthorizeZodTool, - }).map(tool); -}; - -// Use with any of the options above -const tools = convertToAgents(toolsFromGoogle); // or toolsFromMultiple or specificTools -``` - - - - - -### Set up the agent with Arcade tools - -Create an agent and provide it with the Arcade tools: - - - - -```python -from agents import Agent, Runner - -# Create an agent with Gmail tools -google_agent = Agent( - name="Gmail agent", - instructions="You are a helpful assistant that can assist with Google API calls.", - model="gpt-4o-mini", - tools=tools, -) -``` - - - - - -```javascript -import { Agent, Runner, tool } from '@openai/agents'; - -// Create an agent with Arcade tools -const googleAgent = new Agent({ - name: "Gmail agent", - instructions: "You are a helpful assistant that can assist with Google API calls.", - model: "gpt-4o-mini", - tools -}); -``` - - - - -### Run the agent - - - - -Run the agent, providing a user_id for tool authorization: - -```python -try: - result = await Runner.run( - starting_agent=google_agent, - input="What are my latest emails?", - context={"user_id": "{arcade_user_id}"}, - ) - print("Final output:\n\n", result.final_output) -except AuthorizationError as e: - print("Please Login to Google:", e) -``` - - - - -```javascript -const result = await run(googleAgent, "What are my latest emails?"); -``` - - - - - - -### Handle authentication - - - - -If a tool requires authorization, an `AuthorizationError` will be raised with an authorization URL: - -```python -from agents_arcade.errors import AuthorizationError - -try: - # Run agent code from earlier examples - # ... -except AuthorizationError as e: - print(f"Please visit this URL to authorize: {e}") - # The URL contained in the error will take the user to the authorization page -``` - - - - - -If a tool requires authorization, the agent will show a message like this: - -```bash -[Authorize Gmail Access](https://accounts.google.com/o/oauth2/v2/auth?access_type=offline...) -Once you have authorized access, I can retrieve your latest emails. -``` - - - - - -### Complete example - -Here's a complete example putting everything together: - - - - -```python -from agents import Agent, Runner -from arcadepy import AsyncArcade - -from agents_arcade import get_arcade_tools -from agents_arcade.errors import AuthorizationError - - -async def main(): - client = AsyncArcade() - tools = await get_arcade_tools(client, toolkits=["gmail"]) - - google_agent = Agent( - name="Google agent", - instructions="You are a helpful assistant that can assist with Google API calls.", - model="gpt-4o-mini", - tools=tools, - ) - - try: - result = await Runner.run( - starting_agent=google_agent, - input="What are my latest emails?", - context={"user_id": "{arcade_user_id}"}, - ) - print("Final output:\n\n", result.final_output) - except AuthorizationError as e: - print("Please Login to Google:", e) - - -if __name__ == "__main__": - import asyncio - - asyncio.run(main()) -``` - - - - - -Check out the complete working example in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts/src/index.ts). - -```javascript -import Arcade from '@arcadeai/arcadejs'; -import { executeOrAuthorizeZodTool, toZod } from "@arcadeai/arcadejs/lib"; -import { Agent, run, tool } from '@openai/agents'; - -// 1) Initialize Arcade client -const client = new Arcade(); - -// 2) Fetch Gmail MCP Server from Arcade and prepare tools for OpenAI Agents -const googleToolkit = await client.tools.list({ toolkit: "gmail", limit: 30 }); -const tools = toZod({ - tools: googleToolkit.items, - client, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) - executeFactory: executeOrAuthorizeZodTool, -}).map(tool); - -// 3) Create a new agent with the Gmail MCP Server -const googleAgent = new Agent({ - name: "Gmail agent", - instructions: "You are a helpful assistant that can assist with Google API calls.", - model: "gpt-4o-mini", - tools -}); - -// 4) Run the agent -const result = await run(googleAgent, "What are my latest emails?"); - -// 5) Print the result -console.log(result.finalOutput); -``` - - - - - - -## Tips for selecting tools - -- **Relevance**: Pick only the tools you need. Avoid using all tools at once. -- **User identification**: Always provide a unique and consistent `user_id` for each user. Use your internal or database user ID, not something entered by the user. - -## Next steps - -Now that you have integrated Arcade tools into your OpenAI Agents application, you can: - -- Experiment with different MCP Servers, such as "Github" or "LinkedIn" -- Customize the agent's instructions for specific tasks -- Try out multi-agent systems using different Arcade tools -- Build your own custom tools with the Arcade Tool SDK - -Enjoy exploring Arcade and building powerful AI-enabled Python applications! diff --git a/app/en/home/oai-agents/user-auth-interrupts/page.mdx b/app/en/home/oai-agents/user-auth-interrupts/page.mdx deleted file mode 100644 index d76bc6b63..000000000 --- a/app/en/home/oai-agents/user-auth-interrupts/page.mdx +++ /dev/null @@ -1,442 +0,0 @@ ---- -title: "Managing user authorization" -description: "Handle tool authorization with Arcade and OpenAI Agents" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -## User authorization with OpenAI Agents - -In this guide, you will learn how to handle user authorization for Arcade tools in your OpenAI Agents application. When a tool requires authorization, the agent will raise an `AuthorizationError` with a URL for the user to visit and grant permissions. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Install the required packages - -Set up your environment with the following installations: - - - - -```bash -pip install agents-arcade arcadepy -``` - - - - - -```bash -npm install @openai/agents @arcadeai/agents-arcade -``` - - - - - -### Configure your Arcade environment - -Make sure you have set your Arcade API key in the environment, or assign it directly in the code: - -> Need an Arcade API key? Visit the [Get an API key](/home/api-keys) page to create one. - - - - -```python -import os -from arcadepy import AsyncArcade -from agents import Agent, Runner -from agents_arcade import get_arcade_tools -from agents_arcade.errors import AuthorizationError - -# Set your API key -os.environ["ARCADE_API_KEY"] = "YOUR_ARCADE_API_KEY" - -# Initialize the Arcade client -client = AsyncArcade() -``` - - - - - -Add your API key to your environment variables: - -```bash -# In your .env file -ARCADE_API_KEY=YOUR_ARCADE_API_KEY -``` - -```javascript -import Arcade from '@arcadeai/arcadejs'; -import { isAuthorizationRequiredError, toZod } from "@arcadeai/arcadejs/lib"; -import { Agent, run, tool } from '@openai/agents'; - -const client = new Arcade(); -``` - - - - -### Fetch Arcade tools - -Get the tools you need for your agent. In this example, we'll use GitHub tools: - - - - -```python -# Get GitHub tools for this example -tools = await get_arcade_tools(client, toolkits=["github"]) - -# Create an agent with GitHub tools -github_agent = Agent( - name="GitHub agent", - instructions="You are a helpful assistant that can assist with GitHub API calls.", - model="gpt-4o-mini", - tools=tools, -) -``` - - - - - -```javascript -const githubToolkit = await client.tools.list({ toolkit: "github", limit: 30 }); -const arcadeTools = toZod({ - tools: githubToolkit.items, - client, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) -}) -``` - - - - - - -### Handle authorization errors - - - - -When a user needs to authorize access to a tool, the agent will raise an `AuthorizationError`. You can handle it like this: - -```python -try: - result = await Runner.run( - starting_agent=github_agent, - input="Star the arcadeai/arcade-ai repo", - # Pass a unique user_id for authentication - context={"user_id": "{arcade_user_id}"}, - ) - print("Final output:\n\n", result.final_output) -except AuthorizationError as e: - # Display the authorization URL to the user - print(f"Please Login to GitHub: {e}") - # The error contains the authorization URL that the user should visit -``` - - - - - -Choose how to handle authorization errors based on your needs: - -**Default behavior (throws errors):** -```javascript -const arcadeTools = toZod({ - tools: githubToolkit.items, - client, - userId: "", // Replace with your user ID -}); -``` - -Use this when you want to handle authorization flow yourself with custom logic. - -**Auto-handle authorization (recommended):** -```javascript -import { executeOrAuthorizeZodTool } from "@arcadeai/arcadejs/lib"; - -const arcadeTools = toZod({ - tools: githubToolkit.items, - client, - userId: "", // Replace with your user ID - executeFactory: executeOrAuthorizeZodTool, -}); -``` - -This automatically returns authorization URLs instead of throwing errors. - -**Custom error handling:** - -```javascript -import { isAuthorizationRequiredError } from "@arcadeai/arcadejs/lib"; - -const tools = arcadeTools.map((arcadeTool) => { - return tool({ - ...arcadeTool, - errorFunction: async (_, error) => { - if (error instanceof Error && isAuthorizationRequiredError(error)) { - const response = await client.tools.authorize({ - tool_name: arcadeTool.name, - user_id: "", - }); - return `Please login to Google: ${response.url}`; - } - return "Error executing tool" - } - }) -}); -``` - - - - - -### Wait for authorization completion - -You can also wait for the user to complete the authorization before continuing: - - - - -```python -from arcadepy import AsyncArcade -import asyncio - -client = AsyncArcade() - -async def handle_auth_flow(auth_id): - # Display a message to the user - print("Please visit the authorization URL in your browser") - - - # Wait for the user to authenticate - await client.auth.wait_for_completion(auth_id) - - # Check if authorization was successful - if await is_authorized(auth_id): - print("Authorization successful! You can now use the tool.") - return True - else: - print("Authorization failed or timed out.") - return False - -# In your main function -try: - # Run agent code - # ... -except AuthorizationError as e: - auth_id = e.auth_id - if await handle_auth_flow(auth_id): - # Try running the agent again - result = await Runner.run( - starting_agent=github_agent, - input="Star the arcadeai/arcade-ai repo", - context={"user_id": "{arcade_user_id}"}, - ) - print("Final output:\n\n", result.final_output) -``` - - - - - -To wait for authorization completion, follow this approach: - -1. Throw the error to the agent -2. Catch and handle the error while waiting for completion - - - -```javascript -const tools = arcadeTools.map((arcadeTool) => { - return tool({ - ...arcadeTool, - errorFunction: (_, error) => { throw error } // Throw the error to the agent for handling - }) -}); - -while (true) { - try { - const result = await run(googleAgent, "What are my latest emails?"); - console.log(result.finalOutput); - } catch (error) { - // Catch the authorization error and wait for completion - if (error instanceof Error && isAuthorizationRequiredError(error)) { - const response = await client.tools.authorize({ - tool_name: "Gmail_ListEmails", - user_id: "", - }); - if (response.status !== "completed") { - console.log(`Please complete the authorization challenge in your browser: ${response.url}`); - } - - // Wait for the authorization to complete - await client.auth.waitForCompletion(response); - console.log("Authorization completed, retrying..."); - } - } - } -``` - - - - - - - -### Complete example - -Here's a full example that demonstrates the authorization flow with waiting for authentication: - - - - -```python -from arcadepy.auth import wait_for_authorization_completion - -import time - -from agents import Agent, Runner -from arcadepy import AsyncArcade - -from agents_arcade import get_arcade_tools -from agents_arcade.errors import AuthorizationError - - -async def main(): - client = AsyncArcade() - # Use the "github" MCP Server for this example - tools = await get_arcade_tools(client, toolkits=["github"]) - - github_agent = Agent( - name="GitHub agent", - instructions="You are a helpful assistant that can assist with GitHub API calls.", - model="gpt-4o-mini", - tools=tools, - ) - - user_id = "{arcade_user_id}" # Make sure to use a unique user ID - - while True: - try: - result = await Runner.run( - starting_agent=github_agent, - input="Star the arcadeai/arcade-ai repo", - # Pass the user_id for auth - context={"user_id": user_id}, - ) - print("Final output:\n\n", result.final_output) - break # Exit the loop if successful - - except AuthorizationError as e: - auth_url = str(e) - print(f"{auth_url}. Please authenticate to continue.") - - # Wait for the user to authenticate - await client.auth.wait_for_completion(e.result.id) - - -if __name__ == "__main__": - import asyncio - - asyncio.run(main()) -``` - - - - - -Check out the complete working example in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/openai-agents-ts/src/waitForCompletion.ts). - -```javascript -import Arcade from '@arcadeai/arcadejs'; -import { isAuthorizationRequiredError, toZod } from "@arcadeai/arcadejs/lib"; -import { Agent, run, tool } from '@openai/agents'; - -async function main() { - // 1) Initialize Arcade client - const client = new Arcade(); - - // 2) Fetch Gmail MCP Server from Arcade and prepare tools for OpenAI Agents - const googleToolkit = await client.tools.list({ toolkit: "gmail", limit: 30 }); - const tools = toZod({ - tools: googleToolkit.items, - client, - userId: "", // Replace this with your application's user ID (e.g. email address, UUID, etc.) - }).map(tool); - - // 3) Create a new agent with the Gmail MCP Server - const googleAgent = new Agent({ - name: "Gmail agent", - instructions: "You are a helpful assistant that can assist with Google API calls.", - model: "gpt-4o-mini", - tools - }); - - // 4) Run the agent, if authorization is required, wait for it to complete and retry - while (true) { - try { - const result = await run(googleAgent, "What are my latest emails?"); - console.log(result.finalOutput); - break; // Exit the loop if the result is successful - } catch (error) { - if (error instanceof Error && isAuthorizationRequiredError(error)) { - const response = await client.tools.authorize({ - tool_name: "Gmail_ListEmails", - user_id: "", - }); - if (response.status !== "completed") { - console.log(`Please complete the authorization challenge in your browser: ${response.url}`); - } - - // Wait for the authorization to complete - await client.auth.waitForCompletion(response); - console.log("Authorization completed, retrying..."); - } - } - } -} - -main(); -``` - - -This example handles the authentication flow by: - -1. Attempting to run the agent -2. Catching any AuthorizationError -3. Open the authentication URL in a browser -4. Waiting for the user to complete authentication -5. Retrying the operation after a wait period - - - - -## Authentication persistence - -Once a user authorizes with an auth provider, Arcade will remember the authorization for that specific user_id and MCP Server. You don't need to re-authorize each time you run the agent. - -Key points to remember: - -- Always use a consistent and unique `user_id` for each user -- Store the `user_id` securely in your application -- Different MCP Servers require separate authorization flows -- Authorization tokens are managed by Arcade, not your application - -## Next steps - -- Build a user interface to handle authorization flows smoothly -- Explore other Arcade MCP Servers like Google, LinkedIn, or X -- Create multi-step workflows with multiple tools and authorizations -- Learn to build your own custom tools with the Arcade Tool SDK - -By handling Arcade's authorization flow correctly, you can build AI-driven applications that securely integrate with various services while respecting user permissions. Have fun exploring Arcade! diff --git a/app/en/home/observability-platforms/_meta.tsx b/app/en/home/observability-platforms/_meta.tsx new file mode 100644 index 000000000..22b2653f5 --- /dev/null +++ b/app/en/home/observability-platforms/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "quickstarts-placeholder": + "Placeholder for Quickstarts of various observability platforms", +}; diff --git a/app/en/home/observability-platforms/quickstarts-placeholder/page.mdx b/app/en/home/observability-platforms/quickstarts-placeholder/page.mdx new file mode 100644 index 000000000..6f3cdb56d --- /dev/null +++ b/app/en/home/observability-platforms/quickstarts-placeholder/page.mdx @@ -0,0 +1,7 @@ +# Placeholder for Quickstarts of various observability platforms + +Documentation coming soon. + +## Overview + +This section will contain detailed information about integrating Arcade with various observability platforms. \ No newline at end of file diff --git a/app/en/home/open-agents/_meta.tsx b/app/en/home/open-agents/_meta.tsx new file mode 100644 index 000000000..27ad4a394 --- /dev/null +++ b/app/en/home/open-agents/_meta.tsx @@ -0,0 +1,3 @@ +export default { + "quickstart-python": "Quickstart (Python)", +}; diff --git a/app/en/home/open-agents/quickstart-python/page.mdx b/app/en/home/open-agents/quickstart-python/page.mdx new file mode 100644 index 000000000..eb1d1c511 --- /dev/null +++ b/app/en/home/open-agents/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAgents with Python. diff --git a/app/en/home/quickstart/page.mdx b/app/en/home/quickstart/page.mdx deleted file mode 100644 index 212aba924..000000000 --- a/app/en/home/quickstart/page.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: "Start using Arcade's Hosted Tools" -description: "Learn how to get started with Arcade's Hosted Tools" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; -import { SignupLink } from "@/app/_components/analytics"; - -# Arcade's Hosted Tools Quickstart - -Arcade gives your AI agents the power to act. With Arcade's Hosted Tools, your AI can send Gmail, update Notion, message in Slack, and more. - - - - -Install and use the Arcade client to call Arcade Hosted Tools. - - - - - -- An Arcade account -- An [Arcade API key](/home/api-keys) -- The [`uv` package manager](https://docs.astral.sh/uv/getting-started/installation/) - - - - - -- Install the Arcade client -- Execute your first tool using the Arcade client -- Authorize a tool to star a GitHub repository on your behalf - - - - - - -### Install the Arcade client - - - - - In your terminal, run the following command to install the Python client package `arcadepy`: - -```bash -uv pip install arcadepy -``` - - - - - In your terminal, run the following command to install the JavaScript client package `@arcadeai/arcadejs`: - -```bash -npm install @arcadeai/arcadejs -``` - - - - - -### Instantiate and use the client - - - - - -Create a new script called `example.py`: - -```python filename="example.py" -from arcadepy import Arcade - -# You can also set the `ARCADE_API_KEY` environment variable instead of passing it as a parameter. - -client = Arcade(api_key="{arcade_api_key}") - -# Arcade needs a unique identifier for your application user (this could be an email address, a UUID, etc). - -# In this example, use the email you used to sign up for Arcade.dev: - -user_id = "{arcade_user_id}" - -# Let's use the `Math.Sqrt` tool from the Arcade Math MCP Server to get the square root of a number. - -response = client.tools.execute( - tool_name="Math.Sqrt", - input={"a": '625'}, - user_id=user_id, -) - -print(f"The square root of 625 is {response.output.value}") - -# Now, let's use a tool that requires authentication to star a GitHub repository - -auth_response = client.tools.authorize( -tool_name="GitHub.SetStarred", -user_id=user_id, -) - -if auth_response.status != "completed": - print(f"Click this link to authorize: `{auth_response.url}`. The process will continue once you have authorized the app." ) # Wait for the user to authorize the app - client.auth.wait_for_completion(auth_response.id); - -response = client.tools.execute( - tool_name="GitHub.SetStarred", - input={ - "owner": "ArcadeAI", - "name": "arcade-mcp", - "starred": True, - }, - user_id=user_id, -) - -print(response.output.value) - -``` - - - - - -Create a new script called `example.mjs`: - -```javascript filename="example.mjs" -import Arcade from "@arcadeai/arcadejs"; - -// You can also set the `ARCADE_API_KEY` environment variable instead of passing it as a parameter. -const client = new Arcade({ - apiKey: "{arcade_api_key}", -}); - -// Arcade needs a unique identifier for your application user (this could be an email address, a UUID, etc). -// In this example, use the email you used to sign up for Arcade.dev: -let userId = "{arcade_user_id}"; - -// Let's use the `Math.Sqrt` tool from the Arcade Math MCP Server to get the square root of a number. -const response_sqrt = await client.tools.execute({ - tool_name: "Math.Sqrt", - input: { a: "625" }, - user_id: userId, -}); - -console.log(response_sqrt.output.value); - -// Now, let's use a tool that requires authentication - -const authResponse = await client.tools.authorize({ - tool_name: "GitHub.SetStarred", - user_id: userId, -}); - -if (authResponse.status !== "completed") { - console.log( - `Click this link to authorize: \`${authResponse.url}\`. The process will continue once you have authorized the app.` - ); - // Wait for the user to authorize the app - await client.auth.waitForCompletion(authResponse.id); -} - -const response_github = await client.tools.execute({ - tool_name: "GitHub.SetStarred", - input: { - owner: "ArcadeAI", - name: "arcade-mcp", - starred: true, - }, - user_id: userId, -}); - -console.log(response_github.output.value); -``` - - - - - -### Run the code - - - - - - ```bash - uv run example.py - > The square root of 625 is 25 - > Successfully starred the repository ArcadeAI/arcade-mcp - ``` - - - - - ```bash - node example.mjs - > The square root of 625 is 25 - > Successfully starred the repository ArcadeAI/arcade-mcp - ``` - - - - - - -## Next Steps - -In this simple example, we call the tool methods directly. In your real applications and agents, you'll likely be letting the LLM decide which tools to call - learn more about using Arcade with Frameworks in the [Frameworks](/home/langchain/use-arcade-tools) section, or [how to build your own tools](/home/build-tools/create-a-mcp-server). diff --git a/app/en/home/security-section/_meta.tsx b/app/en/home/security-section/_meta.tsx new file mode 100644 index 000000000..ed097de59 --- /dev/null +++ b/app/en/home/security-section/_meta.tsx @@ -0,0 +1,6 @@ +export default { + "identity-providers": "Supported Identity Providers", + "platform-security": "Platform Security", + "enterprise-sso": "Enterprise Single Sign On", + "rbac-config": "Configuring Role Based Access Control for your organization", +}; diff --git a/app/en/home/security-section/enterprise-sso/page.mdx b/app/en/home/security-section/enterprise-sso/page.mdx new file mode 100644 index 000000000..c02c86065 --- /dev/null +++ b/app/en/home/security-section/enterprise-sso/page.mdx @@ -0,0 +1,7 @@ +# enterprise-sso + +Documentation coming soon. + +## Overview + +This section will contain detailed information about enterprise-sso. diff --git a/app/en/home/security-section/identity-providers/page.mdx b/app/en/home/security-section/identity-providers/page.mdx new file mode 100644 index 000000000..68db0a481 --- /dev/null +++ b/app/en/home/security-section/identity-providers/page.mdx @@ -0,0 +1,7 @@ +# identity-providers + +Documentation coming soon. + +## Overview + +This section will contain detailed information about identity-providers. diff --git a/app/en/home/security-section/platform-security/page.mdx b/app/en/home/security-section/platform-security/page.mdx new file mode 100644 index 000000000..b36cca51b --- /dev/null +++ b/app/en/home/security-section/platform-security/page.mdx @@ -0,0 +1,7 @@ +# Platform Security + +Documentation coming soon. + +## Overview + +This section will contain detailed information about platform-security. \ No newline at end of file diff --git a/app/en/home/security-section/rbac-config/page.mdx b/app/en/home/security-section/rbac-config/page.mdx new file mode 100644 index 000000000..8886db539 --- /dev/null +++ b/app/en/home/security-section/rbac-config/page.mdx @@ -0,0 +1,7 @@ +# rbac-config + +Documentation coming soon. + +## Overview + +This section will contain detailed information about rbac-config. diff --git a/app/en/home/security-section/soc-2/page.mdx b/app/en/home/security-section/soc-2/page.mdx new file mode 100644 index 000000000..09f76374e --- /dev/null +++ b/app/en/home/security-section/soc-2/page.mdx @@ -0,0 +1,7 @@ +# soc-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about soc-2. diff --git a/app/en/home/security/page.mdx b/app/en/home/security/page.mdx deleted file mode 100644 index 1bed172bd..000000000 --- a/app/en/home/security/page.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Security Research Program" -description: "Report security vulnerabilities and help us build safe and reliable tools" ---- - -# Security Research Program - -At Arcade, security is fundamental to our mission of building safe and reliable tools. We recognize that the security research community plays a valuable role in identifying potential vulnerabilities. - -## Scope - -Our program covers security issues in: -* Arcade production services and APIs -* Agent authentication and authorization mechanisms -* Data handling and storage systems -* Published open-source components - -## What we're looking for - -We're interested in reports about: -* Authentication or authorization bypasses -* Data exposure or leakage -* Injection vulnerabilities -* Logic flaws affecting agent behavior -* Issues that could compromise user data or agent integrity - -## Reporting process - -Please email [security@arcade.dev](mailto:security@arcade.dev) with: -* A clear description of the issue -* Steps to reproduce -* Potential impact assessment -* Any relevant proof-of-concept code (please be responsible) - -We'll acknowledge receipt within 72 hours and aim to provide an initial assessment within one week. - -## Guidelines - -* Please allow us reasonable time to address issues before public disclosure -* Avoid automated scanning that could impact service availability -* Do not access or modify other users' data -* Keep any discovered vulnerabilities confidential until resolved - -## Recognition - -While we're a small team with limited resources, we appreciate the effort researchers put into improving our security. We'll credit researchers (with permission) in our security updates and may provide modest rewards for significant findings on a case-by-case basis. - -For questions about this program, please contact [security@arcade.dev](mailto:security@arcade.dev). - diff --git a/app/en/home/serve-tools/_meta.tsx b/app/en/home/serve-tools/_meta.tsx deleted file mode 100644 index c7e61f707..000000000 --- a/app/en/home/serve-tools/_meta.tsx +++ /dev/null @@ -1,4 +0,0 @@ -export default { - "arcade-deploy": "Arcade Deploy", - "securing-arcade-mcp": "Securing Arcade MCP", -}; diff --git a/app/en/home/serve-tools/arcade-deploy/page.mdx b/app/en/home/serve-tools/arcade-deploy/page.mdx deleted file mode 100644 index 7157bbd00..000000000 --- a/app/en/home/serve-tools/arcade-deploy/page.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "Cloud deployments with Arcade Deploy" -description: "Learn how to deploy a worker with Arcade Deploy" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; -import { SignupLink } from "@/app/_components/analytics"; - -# Deploying to the cloud with Arcade Deploy - -Running your MCP servers locally is very convenient during development and testing. Once your MCP server is mature, however, you may want to access it from any MCP client, or to facilitate multi-user support. Doing all that from your computer comes with the complexity of running and maintaining a server, handling auth and high availability for all your users and all the integrations you want to support. Arcade Deploy takes care of all that for you. Your MCP server will be registered to Arcade, adding all the tools you created to the larger tool catalog. From there, you can create MCP Gateways to pick and choose which tools you want to use in your MCP clients, which can be from any connected MCP server. - - - - -This guide shows you how to deploy your MCP Server with Arcade Deploy. - - - - - -- [Arcade account](https://api.arcade.dev/signup) -- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) -- [Create an MCP Server](/home/build-tools/create-a-mcp-server) - - - - - -- How to deploy your existing MCP Server to the cloud with the `arcade deploy` CLI command. -- How to create an MCP Gateway to pick and choose which tools you want to use in your MCP clients. -- How to use Arcade clients to call the tools in your MCP Server. - - - - - - - - ```bash - uv tool install arcade-mcp - ``` - - - This will install the Arcade CLI as a [uv tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it available system wide. - - - - - - - ```bash - pip install arcade-mcp - ``` - - - - - - -## Create an MCP server using Arcade MCP - -If you have not created an MCP server yet, then follow the steps outlined in [this guide](/home/build-tools/create-a-mcp-server) before deploying. - -## Deploy your MCP Server - -Run the deploy command in the directory where you started your MCP server (containing your `pyproject.toml` file) and specify the relative path to your entrypoint file via the `--entrypoint/-e` option. - -```bash -arcade deploy -e src/my_server/server.py -``` - -You must run the command from the directory containing your `pyproject.toml` file. - - -By default, running `arcade deploy` looks for a file named `server.py` in the current directory as the entrypoint file to your MCP server. If your entrypoint file is in a different directory, then you need to specify the relative path. - -```py -from arcade_mcp_server import MCPApp - -app = MCPApp() - -@app.tool -def echo(phrase: Annotated[str, "The phrase to echo"]) -> str: - """Echo a phrase""" - return phrase - -if __name__ == "__main__": - app.run() -``` - - -It is important that your entrypoint file executes `MCPApp.run()` (or `app.run()` if `app` is of type `MCPApp`) when invoked directly. - -We recommend to do it inside an `if __name__ == "__main__":` statement. - - - -You should see output like the following: - -```bash -Validating user is logged in... -✓ {arcade_user_id} is logged in - -Validating pyproject.toml exists in current directory... -✓ pyproject.toml found at /path/to/your/project/pyproject.toml - -Loading .env file from current directory if it exists... -✓ Loaded environment from /path/to/your/project/.env - -Validating server is healthy and extracting metadata before deploying... -✓ Server started on port 8001 -✓ Server is healthy -✓ Found server name: my_server -✓ Found server version: 1.0.0 -✓ Found 3 tools -✓ Found 1 required secret(s) - -Uploading 1 required secret(s) to Arcade... -✓ Uploading 'MY_SECRET_KEY' with value ending in ...ime! -✓ Secret 'MY_SECRET_KEY' uploaded - -Creating deployment package... -✓ Package created (1.8 KB) - - -⠧ Deployment in progress (this may take a few minutes)... - -Recent logs: - data: {"Timestamp":"2025-10-27T16:03:45.429460682Z","Line":"Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details."} - data: {"Timestamp":"2025-10-27T16:03:45.429466232Z","Line":"[GIN-debug] Listening and serving HTTP on :8002"} - data: {"Timestamp":"2025-10-27T16:03:47.577492621Z","Line":"[GIN] 2025/10/27 - 16:03:47 | 200 | 2.888808ms | 10.30.253.232 | GET \"/worker/health\""} - data: {"Timestamp":"2025-10-27T16:03:48.230570179Z","Line":"INFO: 127.0.0.1:53384 - \"GET /worker/health HTTP/1.1\" 200 OK"} - data: {"Timestamp":"2025-10-27T16:03:48.231072632Z","Line":"[GIN] 2025/10/27 - 16:03:48 | 200 | 4.526797ms | 10.30.253.232 | GET \"/worker/health\""} - - -You can safely exit with Ctrl+C at any time. The deployment will continue normally. - -✓ Deployment successful! Server is running. -``` - -## Manage your MCP servers in Arcade - -Navigate to the [Servers](https://api.arcade.dev/dashboard/servers) page in your Arcade dashboard. From there, you will be able to: - -- Monitor the health status of the server -- Delete the server -- Test and execute all the tools -- Manage users connected to the Auth providers -- Manage the secrets for the server -- Create [MCP Gateways](/home/mcp-gateways) - -## Create an MCP Gateway to call the tools in your MCP Server - -Once the MCP server is deployed to Arcade, all the tools in the server will be available in the [tool catalog](https://api.arcade.dev/dashboard/tools) page in your Arcade dashboard. To call the tools from an MCP client, you first need to [create an MCP Gateway](/home/mcp-gateways) to pick and choose which tools you want to use in your MCP clients. - -When creating an MCP gateway, you can select the tools you want to include in the Gateway from any MCP Servers available to the project, including the one you just deployed. - -## Use Arcade clients to call the tools in your MCP Server - -You can use any of the available [Arcade clients](/references) to call the tools in your MCP Server. When using the clients, you are not required to create an MCP Gateway, as the client will handle the connection to all tools in your Arcade project directly. - - - -Your MCP Server is now deployed and managed by Arcade, and ready to be used in your MCP clients! diff --git a/app/en/home/serve-tools/securing-arcade-mcp/page.mdx b/app/en/home/serve-tools/securing-arcade-mcp/page.mdx deleted file mode 100644 index 4b3a8a287..000000000 --- a/app/en/home/serve-tools/securing-arcade-mcp/page.mdx +++ /dev/null @@ -1,15 +0,0 @@ -# Securing Arcade MCP Deployments - -You may have noticed that when you connected to the MCP serer you created with `arcade-mcp`, you could immediately call your tools from local MCP Clients and agents, like Claude and Cursor. This is because the `arcade-mcp` server is *not* secured by any mechanism by default. Most use-cases for MCP servers today are local development or local to a single machine, and we optimize for that use-case. - -However, you can secure your MCP server by deploying it to Arcade (available today) or using OAuth (coming soon). - -## Arcade Deploy -When you `arcade deploy` your MCP server, it will be secured behind the Arcade platform. - -Under the hood, we disable the MCP routes provided by `arcade-mcp`, and use the Arcade Engine as a gateway for your MCP server, which has a number of additional features. Arcade will create a randomized secure secret for your MCP server (via the `ARCADE_WORKER_SECRET` environment variable) so that your server is protected from unauthorized access, as well as being isolated from direct access from outside of the Arcade platform. Servers managed by Arcade (servers that are `arcade deploy`ed) serve `/worker` endpoints that are protected by this secret. The worker endpoints are `worker/health`, `/worker/tools`, and `/worker/tools/invoke`. The health endpoint is not protected by this secret, but the listing tools and tool invocations are. You can explore this locally by setting the same environment variable in your locally. - -Learn more about how to deploy your MCP server to Arcade [here](/home/serve-tools/arcade-deploy). - -## OAuth (Coming soon) -Coming soon, you will be able to secure your MCP server's `/mcp` endpoints with a OAuth Authorization Server (AS) - either using Dynamic Client Registration (DCR) or Client ID Metadata Documents (CIMD). Learn more about how MCP integrates with OAuth [here](https://blog.modelcontextprotocol.io/posts/client_registration/). diff --git a/app/en/home/third-party-apps/_meta.tsx b/app/en/home/third-party-apps/_meta.tsx new file mode 100644 index 000000000..dd0a0e643 --- /dev/null +++ b/app/en/home/third-party-apps/_meta.tsx @@ -0,0 +1,7 @@ +export default { + "mcp-gateway-quickstart-2": + "Calling tools in 3rd party agents, apps, or IDEs", + "mcp-clients-section": "Connecting to a MCP Client", + "evaluation-suite": "Creating an evaluation suite to test tools", + "mcp-gateway-auth": "Adding authentication to your MCP Gateway", +}; diff --git a/app/en/home/third-party-apps/evaluation-suite/page.mdx b/app/en/home/third-party-apps/evaluation-suite/page.mdx new file mode 100644 index 000000000..3012b5582 --- /dev/null +++ b/app/en/home/third-party-apps/evaluation-suite/page.mdx @@ -0,0 +1,7 @@ +# evaluation-suite + +Documentation coming soon. + +## Overview + +This section will contain detailed information about evaluation-suite. diff --git a/app/en/home/third-party-apps/mcp-clients-section/_meta.tsx b/app/en/home/third-party-apps/mcp-clients-section/_meta.tsx new file mode 100644 index 000000000..17570ed1d --- /dev/null +++ b/app/en/home/third-party-apps/mcp-clients-section/_meta.tsx @@ -0,0 +1,5 @@ +export default { + cursor: "Cursor", + "claude-desktop": "Claude Desktop", + "visual-studio-code": "Visual Studio Code", +}; diff --git a/app/en/home/third-party-apps/mcp-clients-section/claude-desktop/page.mdx b/app/en/home/third-party-apps/mcp-clients-section/claude-desktop/page.mdx new file mode 100644 index 000000000..108023a40 --- /dev/null +++ b/app/en/home/third-party-apps/mcp-clients-section/claude-desktop/page.mdx @@ -0,0 +1,7 @@ +# Claude Desktop + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Arcade with Claude Desktop. \ No newline at end of file diff --git a/app/en/home/third-party-apps/mcp-clients-section/cursor/page.mdx b/app/en/home/third-party-apps/mcp-clients-section/cursor/page.mdx new file mode 100644 index 000000000..0c569b441 --- /dev/null +++ b/app/en/home/third-party-apps/mcp-clients-section/cursor/page.mdx @@ -0,0 +1,7 @@ +# Cursor + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Arcade with Cursor. \ No newline at end of file diff --git a/app/en/home/third-party-apps/mcp-clients-section/visual-studio-code/page.mdx b/app/en/home/third-party-apps/mcp-clients-section/visual-studio-code/page.mdx new file mode 100644 index 000000000..c12163956 --- /dev/null +++ b/app/en/home/third-party-apps/mcp-clients-section/visual-studio-code/page.mdx @@ -0,0 +1,7 @@ +# Visual Studio Code + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Arcade with Visual Studio Code. \ No newline at end of file diff --git a/app/en/home/third-party-apps/mcp-gateway-auth/page.mdx b/app/en/home/third-party-apps/mcp-gateway-auth/page.mdx new file mode 100644 index 000000000..a6d6e5428 --- /dev/null +++ b/app/en/home/third-party-apps/mcp-gateway-auth/page.mdx @@ -0,0 +1,7 @@ +# Adding authentication to your MCP Gateway + +Documentation coming soon. + +## Overview + +This section will contain detailed information about adding authentication to your MCP Gateway. \ No newline at end of file diff --git a/app/en/home/third-party-apps/mcp-gateway-quickstart-2/page.mdx b/app/en/home/third-party-apps/mcp-gateway-quickstart-2/page.mdx new file mode 100644 index 000000000..c6b307fe8 --- /dev/null +++ b/app/en/home/third-party-apps/mcp-gateway-quickstart-2/page.mdx @@ -0,0 +1,7 @@ +# mcp-gateway-quickstart-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about mcp-gateway-quickstart-2. diff --git a/app/en/home/tool-writing-basics/_meta.tsx b/app/en/home/tool-writing-basics/_meta.tsx new file mode 100644 index 000000000..562b48c83 --- /dev/null +++ b/app/en/home/tool-writing-basics/_meta.tsx @@ -0,0 +1,9 @@ +export default { + "when-build-tools": "When to build tools", + "compare-server-types": "Compare Server Types", + "create-tool-auth": "Create a tool with auth", + "create-tool-secrets": "Create a tool with secrets", + "runtime-data-access": "Accessing runtime data", + "call-tools-mcp": "Call tools from MCP clients", + "run-evaluations": "Run evaluations", +}; diff --git a/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx b/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx new file mode 100644 index 000000000..d5ecbbf58 --- /dev/null +++ b/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx @@ -0,0 +1,7 @@ +# call-tools-mcp + +Documentation coming soon. + +## Overview + +This section will contain detailed information about call-tools-mcp. diff --git a/app/en/home/tool-writing-basics/compare-server-types/page.mdx b/app/en/home/tool-writing-basics/compare-server-types/page.mdx new file mode 100644 index 000000000..580e3b3c1 --- /dev/null +++ b/app/en/home/tool-writing-basics/compare-server-types/page.mdx @@ -0,0 +1,7 @@ +# compare-server-types + +Documentation coming soon. + +## Overview + +This section will contain detailed information about compare-server-types. diff --git a/app/en/home/tool-writing-basics/create-tool-auth/page.mdx b/app/en/home/tool-writing-basics/create-tool-auth/page.mdx new file mode 100644 index 000000000..412fb1902 --- /dev/null +++ b/app/en/home/tool-writing-basics/create-tool-auth/page.mdx @@ -0,0 +1,7 @@ +# create-tool-auth + +Documentation coming soon. + +## Overview + +This section will contain detailed information about create-tool-auth. diff --git a/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx b/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx new file mode 100644 index 000000000..27de627a4 --- /dev/null +++ b/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx @@ -0,0 +1,7 @@ +# create-tool-secrets + +Documentation coming soon. + +## Overview + +This section will contain detailed information about create-tool-secrets. diff --git a/app/en/home/tool-writing-basics/run-evaluations/page.mdx b/app/en/home/tool-writing-basics/run-evaluations/page.mdx new file mode 100644 index 000000000..ef0cdc212 --- /dev/null +++ b/app/en/home/tool-writing-basics/run-evaluations/page.mdx @@ -0,0 +1,7 @@ +# run-evaluations + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-evaluations. diff --git a/app/en/home/tool-writing-basics/runtime-data-access/page.mdx b/app/en/home/tool-writing-basics/runtime-data-access/page.mdx new file mode 100644 index 000000000..f35802fec --- /dev/null +++ b/app/en/home/tool-writing-basics/runtime-data-access/page.mdx @@ -0,0 +1,7 @@ +# runtime-data-access + +Documentation coming soon. + +## Overview + +This section will contain detailed information about runtime-data-access. diff --git a/app/en/home/tool-writing-basics/when-build-tools/page.mdx b/app/en/home/tool-writing-basics/when-build-tools/page.mdx new file mode 100644 index 000000000..462900ed0 --- /dev/null +++ b/app/en/home/tool-writing-basics/when-build-tools/page.mdx @@ -0,0 +1,7 @@ +# when-build-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about when-build-tools. diff --git a/app/en/home/tool-writing-reference/_meta.tsx b/app/en/home/tool-writing-reference/_meta.tsx new file mode 100644 index 000000000..681c0146e --- /dev/null +++ b/app/en/home/tool-writing-reference/_meta.tsx @@ -0,0 +1,7 @@ +export default { + "organize-mcp-tools": "Organize MCP server tools", + "useful-tool-errors": "Providing useful tool errors", + "retry-tools": "Retry tools with improved prompt", + "migrate-toolkits": "Migrate from toolkits to MCP Servers", + "why-evaluate": "Why evaluate tools?", +}; diff --git a/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx b/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx new file mode 100644 index 000000000..e53ec9998 --- /dev/null +++ b/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx @@ -0,0 +1,7 @@ +# migrate-toolkits + +Documentation coming soon. + +## Overview + +This section will contain detailed information about migrate-toolkits. diff --git a/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx b/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx new file mode 100644 index 000000000..02a6fbf44 --- /dev/null +++ b/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx @@ -0,0 +1,7 @@ +# organize-mcp-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about organize-mcp-tools. diff --git a/app/en/home/tool-writing-reference/retry-tools/page.mdx b/app/en/home/tool-writing-reference/retry-tools/page.mdx new file mode 100644 index 000000000..081f1c136 --- /dev/null +++ b/app/en/home/tool-writing-reference/retry-tools/page.mdx @@ -0,0 +1,7 @@ +# retry-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about retry-tools. diff --git a/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx b/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx new file mode 100644 index 000000000..c250ee99a --- /dev/null +++ b/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx @@ -0,0 +1,7 @@ +# useful-tool-errors + +Documentation coming soon. + +## Overview + +This section will contain detailed information about useful-tool-errors. diff --git a/app/en/home/tool-writing-reference/why-evaluate/page.mdx b/app/en/home/tool-writing-reference/why-evaluate/page.mdx new file mode 100644 index 000000000..da0906e4e --- /dev/null +++ b/app/en/home/tool-writing-reference/why-evaluate/page.mdx @@ -0,0 +1,7 @@ +# why-evaluate + +Documentation coming soon. + +## Overview + +This section will contain detailed information about why-evaluate. diff --git a/app/en/home/triggers-section/_meta.tsx b/app/en/home/triggers-section/_meta.tsx new file mode 100644 index 000000000..25016d02f --- /dev/null +++ b/app/en/home/triggers-section/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "background-agents": "Set up a background agent using events", + "scheduled-executions": "Set up scheduled tool executions", + "direct-api-call": "Direct Third-Party API Call", +}; diff --git a/app/en/home/triggers-section/background-agents/page.mdx b/app/en/home/triggers-section/background-agents/page.mdx new file mode 100644 index 000000000..dee52007f --- /dev/null +++ b/app/en/home/triggers-section/background-agents/page.mdx @@ -0,0 +1,7 @@ +# background-agents + +Documentation coming soon. + +## Overview + +This section will contain detailed information about background-agents. diff --git a/app/en/home/triggers-section/direct-api-call/page.mdx b/app/en/home/triggers-section/direct-api-call/page.mdx new file mode 100644 index 000000000..7f370bd51 --- /dev/null +++ b/app/en/home/triggers-section/direct-api-call/page.mdx @@ -0,0 +1,7 @@ +# direct-api-call + +Documentation coming soon. + +## Overview + +This section will contain detailed information about direct-api-call. diff --git a/app/en/home/triggers-section/scheduled-executions/page.mdx b/app/en/home/triggers-section/scheduled-executions/page.mdx new file mode 100644 index 000000000..c6116c323 --- /dev/null +++ b/app/en/home/triggers-section/scheduled-executions/page.mdx @@ -0,0 +1,7 @@ +# scheduled-executions + +Documentation coming soon. + +## Overview + +This section will contain detailed information about scheduled-executions. diff --git a/app/en/home/use-tools/_meta.tsx b/app/en/home/use-tools/_meta.tsx deleted file mode 100644 index 7661d8b0b..000000000 --- a/app/en/home/use-tools/_meta.tsx +++ /dev/null @@ -1,8 +0,0 @@ -import type { MetaRecord } from "nextra"; - -export default { - "tools-overview": "Introduction", - "get-tool-definitions": "Tool formats", - "types-of-tools": "Types of tools", - "error-handling": "Error handling", -} satisfies MetaRecord; diff --git a/app/en/home/use-tools/error-handling/page.mdx b/app/en/home/use-tools/error-handling/page.mdx deleted file mode 100644 index f9e83926c..000000000 --- a/app/en/home/use-tools/error-handling/page.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: "Tool Error Handling" -description: "Learn how to handle errors when using tools with Arcade's Tool Development Kit (TDK)" ---- - -import { Tabs } from "nextra/components"; -import { ErrorHierarchy } from "@/app/_components/error-hierarchy"; - -# Tool error handling - -When calling tools from your Agent, smart error handling is crucial for creating robust and reliable applications. This guide covers everything you need to know about handling errors from a tool user's perspective. - -## Error handling philosophy - -Arcade's error handling is designed to provide you with as much information as possible about the error that occurred. When an error occurs, Arcade's Engine will return a structured error object that you can use to understand the error and take appropriate action. - - - -## Client error handling examples - -Here's how to handle different types of output errors when executing tools with Arcade's client libraries: - - - -```python -""" -This example demonstrates how to handle different kinds of output errors when executing a tool. -""" - -from arcadepy import Arcade # pip install arcadepy -from arcadepy.types.execute_tool_response import OutputError - - -# Requires arcadepy >= 1.8.0 -def handle_tool_error(error: OutputError) -> None: - """Example of how to identify different kinds of output errors.""" - error_kind = error.kind - if error_kind == OutputError.Kind.TOOL_RUNTIME_BAD_INPUT_VALUE: - # You provided the executed tool with an invalid input value - print(error.message) - elif error_kind == OutputError.Kind.TOOL_RUNTIME_RETRY: - # The tool returned a retryable error. Provide the additional - # prompt content to the LLM and retry the tool call - instructions_for_llm = error.additional_prompt_content - print(instructions_for_llm) - elif error_kind == OutputError.Kind.TOOL_RUNTIME_CONTEXT_REQUIRED: - # The tool requires extra context from the user or orchestrator. - # Provide the additional prompt content to them and then retry the - # tool call with the new context - request_for_context = error.additional_prompt_content - print(request_for_context) - elif error_kind == OutputError.Kind.TOOL_RUNTIME_FATAL: - # The tool encountered a fatal error during execution - print(error.message) - elif error_kind == OutputError.Kind.UPSTREAM_RUNTIME_RATE_LIMIT: - # The tool encountered a rate limit error from an upstream service - # Wait for the specified amount of time and then retry the tool call - seconds_to_wait = error.retry_after_ms / 1000 - print(f"Wait for {seconds_to_wait} seconds before retrying the tool call") - elif error_kind.startswith("UPSTREAM_"): - # The tool encountered an error from an upstream service - print(error.message) - - -client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable -user_id = "{arcade_user_id}" -tool_name = "Reddit.GetPostsInSubreddit" -tool_input = {"subreddit": "programming", "limit": 1} - -# Go through the OAuth flow for the tool -auth_response = client.tools.authorize( - tool_name=tool_name, - user_id=user_id, -) -if auth_response.status != "completed": - print(f"Click this link to authorize: {auth_response.url}") - -client.auth.wait_for_completion(auth_response) - -# Execute the tool -response = client.tools.execute( - tool_name=tool_name, - input=tool_input, - user_id=user_id, - include_error_stacktrace=True, -) -if response.output.error: - handle_tool_error(response.output.error) -``` - - -```javascript -/** - * This example demonstrates how to handle different kinds of output errors when executing a tool. - */ - -import { Arcade } from "@arcadeai/arcadejs"; // npm install @arcadeai/arcadejs - -// Requires @arcadeai/arcadejs >= 1.10.0 -function handleToolError(error) { - const errorKind = error.kind; - if (errorKind === "TOOL_RUNTIME_BAD_INPUT_VALUE") { - // You provided the executed tool with an invalid input value - console.log(error.message); - } else if (errorKind === "TOOL_RUNTIME_RETRY") { - // The tool returned a retryable error. Provide the additional - // prompt content to the LLM and retry the tool call - const instructionsForLLM = error.additional_prompt_content; - console.log(instructionsForLLM); - } else if (errorKind === "TOOL_RUNTIME_CONTEXT_REQUIRED") { - // The tool requires extra context from the user or orchestrator. - // Provide the additional prompt content to them and then retry the - // tool call with the new context - const requestForContext = error.additional_prompt_content; - console.log(requestForContext); - } else if (errorKind === "TOOL_RUNTIME_FATAL") { - // The tool encountered a fatal error during execution - console.log(error.message); - } else if (errorKind === "UPSTREAM_RUNTIME_RATE_LIMIT") { - // The tool encountered a rate limit error from an upstream service - // Wait for the specified amount of time and then retry the tool call - const secondsToWait = error.retry_after_ms / 1000; - console.log(`Wait for ${secondsToWait} seconds before retrying the tool call`); - } else if (errorKind.startsWith("UPSTREAM_")) { - // The tool encountered an error from an upstream service - console.log(error.message); - } -} - -const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable -const userId = "{arcade_user_id}"; -const toolName = "Reddit.GetPostsInSubreddit"; -const toolInput = { subreddit: "programming", limit: 1 }; - -// Go through the OAuth flow for the tool -const authResponse = await client.tools.authorize({ - tool_name: toolName, - user_id: userId, -}); -if (authResponse.status !== "completed") { - console.log(`Click this link to authorize: ${authResponse.url}`); -} - -await client.auth.waitForCompletion(authResponse); - -// Execute the tool -const response = await client.tools.execute({ - tool_name: toolName, - input: toolInput, - user_id: userId, - include_error_stacktrace: true, -}); -if (response.output.error) { - handleToolError(response.output.error); -} -``` - - - -## Error types in Arcade client libraries - -To see the full structure of an OutputError, see [arcade-py OutputError](https://github.com/ArcadeAI/arcade-py/blob/942eb2cf41bc14b6c82f0e4acd8b11ef1978cb8d/src/arcadepy/types/execute_tool_response.py#L12) and [arcade-js OutputError](https://github.com/ArcadeAI/arcade-js/blob/902ef0ce9ff0412ca0d66a862cb4301759d3f87f/src/resources/tools/tools.ts#L166). - -## Error types in MCP clients - -As of now, MCP Clients do not return structured error information, only an error message. Arcade will attempt to include the type of error in the error message, but it is not guaranteed. - -## Best practices - -1. **Let Arcade handle most errors**: There's no need to wrap your tool logic in try/catch blocks unless you need custom error handling. - -2. **Use specific error types**: When you do need to raise errors explicitly, use the most specific error type available. - -3. **Include additional context**: For `RetryableToolError` and `ContextRequiredToolError`, use the `additional_prompt_content` parameter to guide the LLM or user. - -## Building tools with error handling - -To learn more about how to build tools with error handling, see the [Build Tools](/home/build-tools/providing-useful-tool-errors) section. diff --git a/app/en/home/use-tools/get-tool-definitions/page.mdx b/app/en/home/use-tools/get-tool-definitions/page.mdx deleted file mode 100644 index 04ff96c60..000000000 --- a/app/en/home/use-tools/get-tool-definitions/page.mdx +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: "Get Formatted Tool Definitions" -description: "Learn how to get formatted tool definitions using Arcade" ---- - -import { Tabs } from "nextra/components"; -import ToggleContent from "@/app/_components/toggle-content"; - -# Get Formatted Tool Definitions - -When calling tools directly, it can be useful to get tool definitions in a specific model provider's format. The Arcade Client provides methods for getting a tool's definition and also for listing the definitions of multiple tools in a specific model provider's format. - -## Get a single tool definition formatted for a model - -It can be useful to get a tool's definition in a specific model provider's format. For example, you may want to get the `Github.SetStarred` tool's definition in OpenAI's format. - -To do this, you can use the `client.tools.formatted.get` method and specify the tool name and format. - - - -```python -from arcadepy import Arcade - -client = Arcade() - -# Get a specific tool formatted for OpenAI -github_star_repo = client.tools.formatted.get(name="Github.SetStarred", format="openai") - -print(github_star_repo) -``` - - -```js -import Arcade from "@arcadeai/arcadejs"; - -const client = new Arcade(); - -// Get a specific tool formatted for OpenAI -const githubStarRepo = await client.tools.formatted.get("Github.SetStarred", { - format: "openai", -}); - -console.log(githubStarRepo); -``` - - - - - - -```yaml -{ - "type": "function", - "function": { - "name": "Github_SetStarred", - "description": "Star or un-star a GitHub repository.\nFor example, to star microsoft/vscode, you would use:\n```\nset_starred(owner=\"microsoft\", name=\"vscode\", starred=True)\n```", - "parameters": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the repository" - }, - "owner": { - "type": "string", - "description": "The owner of the repository" - }, - "starred": { - "type": "boolean", - "description": "Whether to star the repository or not" - } - }, - "required": ["owner", "name", "starred"] - } - } -} -``` - - - -## Get all tool definitions in a MCP Server formatted for a model - -It can be useful to list tool definitions for a MCP Server in a specific model provider's format. For example, you may want to get the definitions of tools in the `Github` MCP Server in OpenAI's format. - -To do this, you can use the `client.tools.formatted.list` method and specify the MCP Server and format. Since this method returns an iterator of pages, you can cast to a list to get all the tools. - - - -```python -from arcadepy import Arcade - -client = Arcade() - -# Get all tools in the Github MCP Server formatted for OpenAI -github_tools = list(client.tools.formatted.list(format="openai", toolkit="github")) - -# Print the number of tools in the Github MCP Server -print(len(github_tools)) -``` - - -```js -import Arcade from "@arcadeai/arcadejs"; - -const client = new Arcade(); - -// Get all tools in the Github MCP Server formatted for OpenAI -const githubTools = await client.tools.formatted.list({ - format: "openai", - toolkit: "github", -}); - -// Print the number of tools in the Github MCP Server -console.log(githubTools.total_count); -``` - - - - -## Get all tool definitions formatted for a model - -To get all tools formatted for OpenAI, you can use the `client.tools.formatted.list` method without specifying a MCP Server. - - - -```python -from arcadepy import Arcade - -client = Arcade() - -# Get all tools formatted for OpenAI -all_tools = list(client.tools.formatted.list(format="openai")) - -# Print the number of tools -print(len(all_tools)) -``` - - -```js -import Arcade from "@arcadeai/arcadejs"; - -const client = new Arcade(); - -// Get all tools formatted for OpenAI -const allTools = await client.tools.formatted.list({ format: "openai" }); - -// Print the number of tools -console.log(allTools.total_count); -``` - - - -## Get Zod Tool Definitions - -[Zod](https://zod.dev) is a TypeScript-first schema validation library that helps you define and validate data structures. The [Arcade JS](https://github.com/ArcadeAI/arcade-js) client offers methods to convert Arcade tool definitions into Zod schemas, providing type safety and validation while enabling seamless integration with AI frameworks like LangChain, Vercel AI SDK, and Mastra AI. Using Zod with Arcade provides: - -1. **Type Safety**: Runtime validation of tool inputs and outputs against their defined types -2. **TypeScript Integration**: Provides excellent TypeScript support with automatic type inference -3. **Framework Compatibility**: Direct integration with LangChain, Vercel AI SDK, and Mastra AI - -### Convert to Zod Format - -Arcade offers three ways to convert your tools into Zod schemas, each for different use cases: - -#### 1. Convert to array of Zod tools - -This method returns an array of tools with Zod validation. - -```ts -import { toZod } from "@arcadeai/arcadejs/lib" - -const googleToolkit = await arcade.tools.list({ - limit: 20, - toolkit: "gmail", -}); - -const tools = toZod({ - tools: googleToolkit.items, - client: arcade, - userId: "", -}) -``` - -#### 2. Convert to object of Zod tools - -This method returns an object with tool names as keys, allowing direct access to tools by name: - -```ts -import { toZodToolSet } from "@arcadeai/arcadejs/lib" - -const googleToolkit = await arcade.tools.list({ - limit: 20, - toolkit: "gmail", -}); - -const tools = toZodToolSet({ - tools: googleToolkit.items, - client: arcade, - userId: "", -}) - -const emails = await tools.Gmail_ListEmails.execute({ - limit: 10, -}); -``` - -#### 3. Convert a single tool - -When you only need to work with a specific tool, use this method to convert just that tool to a Zod schema: - -```ts -import { createZodTool } from "@arcadeai/arcadejs/lib" - -const listEmails = await arcade.tools.get("Gmail_ListEmails"); - -const listEmailsTool = createZodTool({ - tool: listEmails, - client: arcade, - userId: "", -}); - -const emails = await listEmailsTool.execute({ - limit: 10, -}); -``` - -### Handle Authorization -When working with tools that require user authorization (like Gmail, GitHub, Slack, etc.), Arcade provides two approaches to handle the authorization flow when using Zod-converted tools: - -#### Option 1: Manual handling - -When you convert Arcade tools to Zod without adding an `executeFactory`, Arcade will try to run tools directly. For tools that need permission (like Gmail or Slack), you'll see a `PermissionDeniedError` if the user hasn't given access yet. - -This approach gives you complete control over the authorization flow, making it perfect for custom UI implementations or complex workflows. You'll have full flexibility to design your own user experience, but you'll need to handle authorization flows and error states manually in your code. - -```ts -import { PermissionDeniedError } from "@arcadeai/arcadejs" - -const tools = toZodToolSet({ - tools: googleToolkit.items, - client: arcade, - userId: "", -}) - -try { - const result = await tools.Gmail_ListEmails.execute({ - limit: 10, - }); - console.log(result); -} catch (error) { - if (error instanceof PermissionDeniedError) { - // You can use the `arcade.tools.authorize` method to get an authorization URL for the user - const authorizationResponse = await arcade.tools.authorize({ - tool_name: "Gmail.ListEmails", - user_id: "", - }); - console.log(authorizationResponse.url); - } else { - console.error("Error executing tool:", error); - } -} -``` - -#### Option 2: Execute and authorize tool - -Arcade offers a more convenient way to handle tool execution and initial authorization steps. When converting tools to Zod, you can add the `executeOrAuthorizeZodTool` helper to the `executeFactory`. With this helper, your code no longer needs to catch a `PermissionDeniedError` for tools requiring permissions (as shown in Option 1). Instead, if the user hasn't yet granted access, the `execute` method will return an `ToolAuthorizationResponse` object that contains the authorization URL. - -This approach simplifies your code by: - -1. Attempting to execute the tool. -2. If permissions are missing, it returns an object containing the authorization URL. This eliminates the need for both a `try...catch` block for `PermissionDeniedError` and a separate call (like `arcade.tools.authorize`) just to retrieve this URL. -3. If the tool is already authorized, it executes directly. Arcade remembers user authorizations, so once a user approves access, subsequent calls using this helper will execute the tool without prompting for authorization again. - -While this helper streamlines obtaining the authorization URL, you are still responsible for presenting this URL to the user. It's particularly useful for straightforward implementations where you want to reduce boilerplate. - -```ts -import { executeOrAuthorizeZodTool } from "@arcadeai/arcadejs" - -const tools = toZodToolSet({ - tools: googleToolkit.items, - client: arcade, - userId: "", - executeFactory: executeOrAuthorizeZodTool, // Automatically handles tool authorization flows, including generating auth URLs -}); - -const result = await tools.Gmail_ListEmails.execute({ - limit: 10, -}); - -if ("authorization_required" in result && result.authorization_required) { - console.log( - `Please visit ${result.authorization_response.url} to authorize the tool`, - ); -} else { - console.log(result); -} -``` diff --git a/app/en/home/use-tools/tools-overview/page.mdx b/app/en/home/use-tools/tools-overview/page.mdx deleted file mode 100644 index 231f09542..000000000 --- a/app/en/home/use-tools/tools-overview/page.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "What are tools?" -description: Overview of language model tool calling and how to use tools with Arcade ---- - -# What are tools? - -Language models excel at text generation but struggle with tasks like calculations, data retrieval, or interacting with external systems. To make an analogy, these models have impressive _brains_ or reasoning capabilities, but lack the _hands_ to interact with the digital world. - -To solve this, many AI models support tool calling (sometimes referred to as 'function calling'). - -## The use case for tool-calling - -Say a colleague shares a document with you on Google Drive, and you'd like an LLM to help you analyze it. - -You could go to your Drive/Docs, open the document, copy its contents, and paste it into your chat. But what if the LLM could do this for you? The Arcade Google Docs MCP Server provides a [`SearchAndRetrieveDocuments`](/mcp-servers/productivity/google-docs#googledocssearchandretrievedocuments) tool. By calling it, the LLM can find and read the document without you having to do anything. - -After analyzing the document, you decide that a meeting is needed with your colleague. You can ask the LLM to schedule a meeting and it will use the [Google Calendar MCP Server](/mcp-servers/productivity/google-calendar) to do it without you needing to leave the chat. - -Or you could ask the LLM to send a summary of the analysis to your colleague by email and it would use the [Gmail MCP Server](/mcp-servers/productivity/gmail) for that. - -## Possibilities for Application and AI Agent developers - -Tool-calling combines the reasoning power of LLMs with virtually any action available through APIs or code execution. - -With the Arcade SDKs, it is easy to build applications and AI Agents that can leverage tool-calling in order to provide an LLM-powered experience to users in a secure and privacy-forward way. - -## How tool calling works - -AI models that support tool calling can determine when and how to use specific tools to fulfill a user's request. The developer decides which tools to make available to the model, whether existing tools or tools they've built themselves. - -In the example above, when the user asks: "_help me analyze the 'Project XYZ' Google document shared by John_", the LLM can use its reasoning capabilities to: - -1. Recognize that it needs to access external data; -1. Evaluate that the `GoogleDocs.SearchAndRetrieveDocuments` tool is the best way to get that data; -1. Call the tool with the appropriate parameters; -1. Read the document content and use it to answer the user's questions. - -## The authorization problem - -One challenge to make all that happen is authorization. How do you give the LLM permission to access someone's Google Docs and Gmail in a secure and convenient way? - -Arcade solves this problem by providing a standardized [interface for authorization](/home/auth/how-arcade-helps), as well as pre-built auth providers for [popular services](/home/auth-providers) such as Google, Dropbox, GitHub, Notion, and many more. - -Our SDK also [allows you to integrate](/home/auth-providers/oauth2) LLMs with any OAuth 2.0-compliant API. - -## Tool Augmented Generation (TAG) - -Similar to Retrieval Augmented Generation (RAG), tool calling allows the AI to use external data to answer questions. Unlike RAG, tool calling is more flexible and allows the AI to use tools that are much more diverse than text or vector search alone. - -The following is a diagram of how tool calling is used to provide context to a language model similar to RAG. - -Tool calling diagram 1 - -First, a language model is given a user's request. The model then determines if it needs to use a tool to fulfill the request. If so, the model selects the appropriate tool from the tools listed in the request. - -The model then predicts the parameters of that tool and passes these parameters back to the client application. - -Tool calling diagram 2 - -Now that the tool has been executed, the model can use the output to generate a response. - -Tool calling diagram 3 - -This process shows the general outline of the Tool Augmented Generation (TAG) process at a high level. - -### Next steps - -- Explore the [MCP Servers](/mcp-servers) available on Arcade -- Build your own [custom MCP Server](/home/build-tools/create-a-mcp-server) diff --git a/app/en/home/use-tools/types-of-tools/page.mdx b/app/en/home/use-tools/types-of-tools/page.mdx deleted file mode 100644 index 71eab7fe1..000000000 --- a/app/en/home/use-tools/types-of-tools/page.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Types of Tools" -description: "Learn about Optimized and Starter tools" ---- - -# Types of Tools - -Arcade offers two types of tools: - -- Starter tools -- Optimized tools - -The distinction is merely a matter of how they are designed. Both types of tools can be used seamlessly in the same way. There is no difference 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). - -Before we understand the two types, let's first understand the background for why we need to differentiate between them. - -## 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. - -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. - -For instance, consider the following user prompt: - -> "Send a DM to John asking about a project update" - -The data model mismatches are: - -| Dimension | Chat interface | Slack HTTP API | -| --------- | -------------------------------------- | --------------------------------------- | -| Action | Send message to a person | Send message to a channel | -| Argument | `username = "John"` | `channel_id = ???` | - -In order to bridge the gap in the data models, the LLM has to make multiple API calls: - -1. Retrieve the current user's Slack ID -2. Browse the list of users to find John's ID -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. - -## 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. - -Following the example above, our Slack MCP Server offers the [`Slack.SendMessage`](/mcp-servers/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. We understand that your Agent or chatbot project might need capabilities not yet covered by our Optimized MCP Servers. For this reason, we also offer low-level Starter MCP Servers. - -## Starter tools - -To provide your Agent or chatbot with more freedom to interact with the upstream services, we offer Starter MCP Servers. - -Starter tools are heavily influenced by 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, Starter 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 Starter tool with your Agents or chatbots before using it in production. - -When your Agent's needs are covered by an Optimized tool, we recommend using it instead of a Starter one. Use Starter tools as a complement. Carefully engineer your prompts to ensure your Agent can call them safely. diff --git a/app/en/home/vercelai/_meta.tsx b/app/en/home/vercelai/_meta.tsx index 6305a7f2b..c1d2a14cd 100644 --- a/app/en/home/vercelai/_meta.tsx +++ b/app/en/home/vercelai/_meta.tsx @@ -1,3 +1,3 @@ export default { - "using-arcade-tools": "Using Arcade tools", + "quickstart-typescript": "Quickstart (Typescript)", }; diff --git a/app/en/home/vercelai/quickstart-typescript/page.mdx b/app/en/home/vercelai/quickstart-typescript/page.mdx new file mode 100644 index 000000000..41312ce5a --- /dev/null +++ b/app/en/home/vercelai/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Vercel AI with TypeScript. \ No newline at end of file diff --git a/app/en/home/vercelai/using-arcade-tools/page.mdx b/app/en/home/vercelai/using-arcade-tools/page.mdx deleted file mode 100644 index 5471ee846..000000000 --- a/app/en/home/vercelai/using-arcade-tools/page.mdx +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: "Use Arcade tools with Vercel AI SDK" -description: "Integrate Arcade tools into your Vercel AI applications" ---- - -import { Steps, Tabs, Callout } from "nextra/components"; - -## Use Arcade with Vercel AI SDK - -The [Vercel AI SDK](https://sdk.vercel.ai/) is an open-source library that simplifies the process of building AI-powered applications. It provides a consistent interface for working with various AI providers and includes several useful features: - -- Streaming AI responses for real-time interactions -- Framework-agnostic support for React, Next.js, Vue, Nuxt, and SvelteKit. -- Easy switching between AI providers with a single line of code - -Let's supercharge your Vercel AI SDK applications with Arcade's tools. You'll get instant access to production-ready tools for working with Google, Slack, GitHub, LinkedIn, and many other popular services, all with built-in authentication. Browse our [complete MCP Server catalog](/mcp-servers) to discover what you can build. - -In this guide, we'll show you how to use Arcade's Gmail MCP Server to create an AI agent that can read and summarize emails. You can find the complete code in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/tree/main/examples/ai-sdk) or follow along below. - -## Getting started - - - -### Install the required dependencies - -We'll use the `@ai-sdk/openai` package in this example, but you can use any AI provider supported by the Vercel AI SDK. See the [full list of providers](https://ai-sdk.dev/docs/foundations/providers-and-models#ai-sdk-providers). - - - - - -```bash -pnpm add ai @ai-sdk/openai @arcadeai/arcadejs -``` - - - - - -```bash -npm install ai @ai-sdk/openai @arcadeai/arcadejs -``` - - - - - -```bash -yarn install ai @ai-sdk/openai @arcadeai/arcadejs -``` - - - - - -### Get your API keys and set up environment variables - -You'll need two API keys: - -- **OpenAI API key** from [OpenAI dashboard](https://platform.openai.com/api-keys) -- **Arcade API key** from our [Getting your API key guide](/home/api-keys) - -Add them to your environment: - -```bash -OPENAI_API_KEY= -ARCADE_API_KEY= -``` - -### Import Libraries and Initialize Arcade - -```ts -import { openai } from "@ai-sdk/openai"; -import { generateText } from "ai"; -import { Arcade } from "@arcadeai/arcadejs"; -import { - toZodToolSet, - executeOrAuthorizeZodTool, -} from "@arcadeai/arcadejs/lib"; - -const arcade = new Arcade(); -``` - -### Get tools from Arcade's Gmail MCP Server and convert them to Zod - -Arcade offers methods to convert tools into Zod schemas, which is essential since the Vercel AI SDK defines tools using Zod. The `toZodToolSet` method is particularly useful, as it simplifies this integration and makes it easier to use Arcade's tools with the Vercel AI SDK. Learn more about Arcade's Zod integration options [here](/home/use-tools/get-tool-definitions#get-zod-tool-definitions). - -```ts -// Get Arcade's gmail MCP Server -const googleToolkit = await arcade.tools.list({ toolkit: "gmail", limit: 30 }); -const googleTools = toZodToolSet({ - tools: googleToolkit.items, - client: arcade, - userId: "", // Your app's internal ID for the user (an email, UUID, etc). It's used internally to identify your user in Arcade - executeFactory: executeOrAuthorizeZodTool, // Checks if tool is authorized and executes it, or returns authorization URL if needed -}); -``` - -### Generate text with the tools - -```ts -const result = await generateText({ - model: openai("gpt-4o-mini"), - prompt: "Read my last email and summarize it in a few sentences", - tools: googleTools, - maxSteps: 5, -}); - -console.log(result.text); -``` - - -On your first run, you'll get an authorization message with a link to connect your Google account. Open it in your browser to complete the setup. That's all you need to do! Arcade will remember your approval for future requests. - - - -You can see the full code in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/ai-sdk/generateText.js). - -## Stream the response - -Vercel AI SDK supports streaming responses. This creates a more engaging, chat-like experience as the responses appear progressively instead of waiting for the complete answer. - -To enable streaming, make these key changes: - -1. Import `streamText` instead of `generateText` -2. Use `streamText` to create a streamable response -3. Process the response chunk by chunk - -```ts -import { streamText } from "ai"; - -const { textStream } = streamText({ - model: openai("gpt-4o-mini"), - prompt: "Read my last email and summarize it in a few sentences", - tools: googleTools, - maxSteps: 5, -}); - -for await (const chunk of textStream) { - process.stdout.write(chunk); -} -``` - -You can see the full code in our [GitHub repository](https://github.com/ArcadeAI/arcade-ai/blob/main/examples/ai-sdk/index.js). - -## How to use other MCP Servers - -You just need to change the MCP Server parameter in the `list` method. For example, to use Slack MCP Server: - -```ts -const slackToolkit = await arcade.tools.list({ toolkit: "Slack", limit: 30 }); -``` - -Browse our [complete MCP Server catalog](/mcp-servers) to see all available MCP Servers and their capabilities. Each MCP Server comes with pre-built tools that are ready to use with your AI applications. Arcade also is the best way to create your own custom tools and MCP Servers - learn more [here](/home/build-tools/create-a-mcp-server). diff --git a/app/en/home/when-build-tools/page.mdx b/app/en/home/when-build-tools/page.mdx deleted file mode 100644 index 8e61729ae..000000000 --- a/app/en/home/when-build-tools/page.mdx +++ /dev/null @@ -1,34 +0,0 @@ -# When to Build Tools - -This is a placeholder page about when to build custom tools. - -## Overview - -Overview page to direct to the various scenarios in which you'd build a tool. - -## Scenarios for Building Tools - -### New Functionality -Build tools when you need agent functionality that doesn't exist in current toolkits. - -### Performance Optimization -Create custom tools to get more performance from existing agent capabilities. - -### Model Compatibility -Update tools to work with the newest language models and their capabilities. - -### Integration Requirements -Build tools for specific APIs or systems not covered by existing toolkits. - -## Decision Framework - -1. **Evaluate existing tools** - Check if current tools meet your needs -2. **Assess performance** - Determine if custom tools would improve results -3. **Consider maintenance** - Factor in ongoing support requirements -4. **Plan for testing** - Create evaluation suites for new tools - -## Next Steps - -- [Compare Server Types](/en/home/compare-server-types) -- [Build MCP Server](/en/home/build-tools) -- [Create Evaluation Suite](/en/home/evaluate-tools) \ No newline at end of file From 9bdf4b36e4ce6eb7ce7c9eac6bd05d60bac2e036 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Mon, 8 Dec 2025 15:21:41 -0800 Subject: [PATCH 03/11] reasonable example --- app/en/home/_meta.tsx | 251 +++++++----------- app/en/home/agentic-architecture/_meta.tsx | 4 + .../architecture-patterns/_meta.tsx | 3 + .../architecture-patterns/page.mdx | 7 + .../supervisor-architecture/page.mdx | 7 + .../kinds-of-agents/_meta.tsx | 4 + .../kinds-of-agents/agent-apps/page.mdx | 7 + .../background-agents/page.mdx | 7 + .../kinds-of-agents/page.mdx | 7 + app/en/home/agentic-architecture/page.mdx | 7 + app/en/home/api/page.mdx | 7 + app/en/home/arcade-clients/page.mdx | 7 + app/en/home/arcade-mcp/page.mdx | 7 + app/en/home/auth-and-secrets/page.mdx | 7 + app/en/home/blog/page.mdx | 7 + app/en/home/changelog-page/page.mdx | 7 + app/en/home/concepts/_meta.tsx | 6 + app/en/home/concepts/page.mdx | 7 + app/en/home/concepts/tool-types/page.mdx | 7 + app/en/home/creating-tools/_meta.tsx | 10 + .../creating-tools/error-handling/page.mdx | 7 + .../home/creating-tools/migrate-mcp/page.mdx | 7 + .../creating-tools/new-functionality/page.mdx | 7 + .../creating-tools/newest-models/page.mdx | 7 + app/en/home/creating-tools/page.mdx | 3 + .../creating-tools/performance-tools/page.mdx | 7 + .../home/creating-tools/tool-basics/page.mdx | 7 + app/en/home/deployment-hosting/page.mdx | 7 + app/en/home/examples/page.mdx | 7 + app/en/home/guides/_meta.tsx | 1 + app/en/home/guides/page.mdx | 7 + app/en/home/orchestrators/page.mdx | 7 + app/en/home/quickstarts/_meta.tsx | 5 + .../home/quickstarts/call-tool-easy/page.mdx | 7 + .../call-tool-personal-agent/page.mdx | 7 + app/en/home/quickstarts/page.mdx | 7 + .../home/quickstarts/spin-up-server/page.mdx | 7 + app/en/home/scaling/_meta.tsx | 3 + app/en/home/scaling/custom-auth/page.mdx | 7 + app/en/home/scaling/page.mdx | 7 + app/en/home/security/page.mdx | 7 + app/en/home/setup/_meta.tsx | 4 + app/en/home/setup/api-key/page.mdx | 7 + .../home/setup/connect-arcade-docs/page.mdx | 7 + app/en/home/setup/page.mdx | 7 + app/en/home/status-page/page.mdx | 7 + app/en/home/using-tools/_meta.tsx | 8 + .../using-tools/agent-functionality/page.mdx | 7 + app/en/home/using-tools/custom-apps/page.mdx | 7 + .../home/using-tools/multi-user-auth/page.mdx | 7 + app/en/home/using-tools/page.mdx | 3 + .../using-tools/third-party-apps/page.mdx | 7 + app/en/home/using-tools/triggers/page.mdx | 7 + app/en/home/what-is-agent/page.mdx | 7 + app/en/home/why-agents-call-tools/page.mdx | 7 + 55 files changed, 447 insertions(+), 152 deletions(-) create mode 100644 app/en/home/agentic-architecture/_meta.tsx create mode 100644 app/en/home/agentic-architecture/architecture-patterns/_meta.tsx create mode 100644 app/en/home/agentic-architecture/architecture-patterns/page.mdx create mode 100644 app/en/home/agentic-architecture/architecture-patterns/supervisor-architecture/page.mdx create mode 100644 app/en/home/agentic-architecture/kinds-of-agents/_meta.tsx create mode 100644 app/en/home/agentic-architecture/kinds-of-agents/agent-apps/page.mdx create mode 100644 app/en/home/agentic-architecture/kinds-of-agents/background-agents/page.mdx create mode 100644 app/en/home/agentic-architecture/kinds-of-agents/page.mdx create mode 100644 app/en/home/agentic-architecture/page.mdx create mode 100644 app/en/home/api/page.mdx create mode 100644 app/en/home/arcade-clients/page.mdx create mode 100644 app/en/home/arcade-mcp/page.mdx create mode 100644 app/en/home/auth-and-secrets/page.mdx create mode 100644 app/en/home/blog/page.mdx create mode 100644 app/en/home/changelog-page/page.mdx create mode 100644 app/en/home/concepts/_meta.tsx create mode 100644 app/en/home/concepts/page.mdx create mode 100644 app/en/home/concepts/tool-types/page.mdx create mode 100644 app/en/home/creating-tools/_meta.tsx create mode 100644 app/en/home/creating-tools/error-handling/page.mdx create mode 100644 app/en/home/creating-tools/migrate-mcp/page.mdx create mode 100644 app/en/home/creating-tools/new-functionality/page.mdx create mode 100644 app/en/home/creating-tools/newest-models/page.mdx create mode 100644 app/en/home/creating-tools/page.mdx create mode 100644 app/en/home/creating-tools/performance-tools/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/page.mdx create mode 100644 app/en/home/deployment-hosting/page.mdx create mode 100644 app/en/home/examples/page.mdx create mode 100644 app/en/home/guides/_meta.tsx create mode 100644 app/en/home/guides/page.mdx create mode 100644 app/en/home/orchestrators/page.mdx create mode 100644 app/en/home/quickstarts/_meta.tsx create mode 100644 app/en/home/quickstarts/call-tool-easy/page.mdx create mode 100644 app/en/home/quickstarts/call-tool-personal-agent/page.mdx create mode 100644 app/en/home/quickstarts/page.mdx create mode 100644 app/en/home/quickstarts/spin-up-server/page.mdx create mode 100644 app/en/home/scaling/_meta.tsx create mode 100644 app/en/home/scaling/custom-auth/page.mdx create mode 100644 app/en/home/scaling/page.mdx create mode 100644 app/en/home/security/page.mdx create mode 100644 app/en/home/setup/_meta.tsx create mode 100644 app/en/home/setup/api-key/page.mdx create mode 100644 app/en/home/setup/connect-arcade-docs/page.mdx create mode 100644 app/en/home/setup/page.mdx create mode 100644 app/en/home/status-page/page.mdx create mode 100644 app/en/home/using-tools/_meta.tsx create mode 100644 app/en/home/using-tools/agent-functionality/page.mdx create mode 100644 app/en/home/using-tools/custom-apps/page.mdx create mode 100644 app/en/home/using-tools/multi-user-auth/page.mdx create mode 100644 app/en/home/using-tools/page.mdx create mode 100644 app/en/home/using-tools/third-party-apps/page.mdx create mode 100644 app/en/home/using-tools/triggers/page.mdx create mode 100644 app/en/home/what-is-agent/page.mdx create mode 100644 app/en/home/why-agents-call-tools/page.mdx diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index 04ac8743a..e4255551e 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -1,4 +1,4 @@ -import { BadgeHelp, Globe, HeartPulse, Home } from "lucide-react"; +import { Home } from "lucide-react"; import type { MetaRecord } from "nextra"; function TitleWithIcon({ @@ -17,11 +17,6 @@ function TitleWithIcon({ } export const meta: MetaRecord = { - "*": { - theme: { - copyPage: true, - }, - }, index: { title: Home, theme: { @@ -31,193 +26,145 @@ export const meta: MetaRecord = { copyPage: false, }, }, - arcade: { - title: Arcade.dev, - href: "https://arcade.dev", + "-- Updates": { + type: "separator", + title: "Updates", }, - "-- Getting Started with tool calling": { + "status-page": "Status", + "changelog-page": "Changelog", + blog: "Blog", + "-- Get Started": { type: "separator", - title: "Getting Started with tool calling", + title: "Get Started", }, - "calling-tools-custom-apps": { - title: "Calling tools in your custom apps", - href: "/calling-tools-custom-apps", + setup: "Setup", + quickstarts: "Quickstarts", + "-- Build": { + type: "separator", + title: "Build", + }, + "using-tools": "Using tools", + "creating-tools": "Creating tools", + orchestrators: "Orchestrators", + scaling: "Scaling", + "agentic-architecture": "Agentic Architecture & Workflows", + examples: "Examples (tutorials and sample code)", + "deployment-hosting": "Deployment and Hosting", + security: "Security", + "-- Learn": { + type: "separator", + title: "Learn", }, - "api-keys": { - title: "Get an API Key", + "what-is-agent": "What's an agent?", + "why-agents-call-tools": "Why and how do agents call tools?", + "auth-and-secrets": "How do auth and secrets work?", + "-- APIs & SDKs": { + type: "separator", + title: "APIs & SDKs", }, - "mcp-gateway-quickstart": { - title: "Calling tools in 3rd party agents, apps, or IDEs", - href: "/mcp-gateway-quickstart", + api: "API", + "arcade-mcp": "Arcade MCP", + "arcade-clients": "Arcade Clients", + "-- Resources": { + type: "separator", + title: "Resources", }, - "mcp-server-quickstart": { - title: "Build MCP Server to write custom tools", - href: "/mcp-server-quickstart", + glossary: "Glossary", + faq: "FAQ", + concepts: "Concepts", + // Hide auto-discovered directories + "api-keys": { + display: "hidden", }, - "sample-agents": { - title: "Sample agents with tool calling", - href: "/sample-agents", + "auth-providers": { + display: "hidden", }, - "configure-arcade-section": { - title: "Configure Arcade", + "calling-tools-custom-apps": { + display: "hidden", }, - "-- Tool Calling": { - type: "separator", - title: "Tool Calling", + changelog: { + display: "hidden", }, - "tool-calling-intro": { - title: "Introduction", - href: "/tool-calling-intro", + "configure-arcade-section": { + display: "hidden", }, - "error-handling": { - title: "Error Handling", - href: "/error-handling", + "contact-us": { + display: "hidden", }, - "third-party-apps": { - title: "In 3rd party applications", + crewai: { + display: "hidden", }, "custom-apps": { - title: "In custom applications", + display: "hidden", }, - "triggers-section": { - title: "Triggers", - }, - "-- Tool Writing": { - type: "separator", - title: "Tool Writing", + "google-adk": { + display: "hidden", }, - "tool-writing-basics": { - title: "Learn the basics", + "hosting-overview": { + display: "hidden", }, "improve-performance": { - title: "Building tools to get more performance out of existing toolkits", - }, - "new-functionality": { - title: "Building tools with agent functionality that doesn't exist", - }, - "newest-models": { - title: "Ensure tools work with the newest models", - }, - "tool-writing-reference": { - title: "Reference", - }, - "-- Configuring Arcade with Agent Orchestrators": { - type: "separator", - title: "Configuring Arcade with Agent Orchestrators", - }, - "orchestrator-overview": { - title: - "Overview to route based on language / orchestration framework combo", - href: "/orchestrator-overview", - }, - "python-quickstart": { - title: "Python Quickstart", - href: "/python-quickstart", - }, - "typescript-quickstart": { - title: "Typescript Quickstart", - href: "/typescript-quickstart", + display: "hidden", }, langchain: { - title: "LangGraph", - }, - "oai-agents": { - title: "OpenAI Agents", - }, - crewai: { - title: "CrewAI", - }, - "open-agents": { - title: "OpenAgents", - }, - "google-adk": { - title: "Google ADK", + display: "hidden", }, mastra: { - title: "Mastra", - }, - vercelai: { - title: "Vercel AI", - }, - "-- Configuring Arcade with Observability Platforms": { - type: "separator", - title: "Configuring Arcade with Observability Platforms", + display: "hidden", }, - "observability-platforms": { - title: "Observability Platforms", + "mcp-clients": { + display: "hidden", }, - "-- Scaling your app to many end-users": { - type: "separator", - title: "Scaling your app to many end-users", + "mcp-gateway-quickstart": { + display: "hidden", }, - "multi-user-auth": { - title: "Set-up secure multi-user auth for your app", - href: "/multi-user-auth", + "new-functionality": { + display: "hidden", }, - "auth-providers": { - title: "Customizing Auth", + "newest-models": { + display: "hidden", }, - "-- Hosting Options": { - type: "separator", - title: "Hosting Options", + "oai-agents": { + display: "hidden", }, - "hosting-overview": { - title: "Overview", - href: "/hosting-overview", + "observability-platforms": { + display: "hidden", }, - "cloud-infrastructure": { - title: "Using Arcade's Cloud Infrastructure", - href: "/cloud-infrastructure", + "open-agents": { + display: "hidden", }, - "on-premise-mcp": { - title: "Using On-premise MCP Servers", - href: "/on-premise-mcp", + "python-quickstart": { + display: "hidden", }, - "engine-config": { - title: "Engine configuration", - href: "/engine-config", + "registry-early-access": { + display: "hidden", }, - "-- Security": { - type: "separator", - title: "Security", + "sample-agents": { + display: "hidden", }, "security-section": { - title: "Security & Compliance", - }, - "-- Guides": { - type: "separator", - title: "Guides", + display: "hidden", }, - glossary: { - title: "Glossary", - }, - faq: { - title: "FAQ", - }, - "connect-docs-ide": { - title: "Connect Arcade Docs to Your IDE", - href: "/connect-docs-ide", + "third-party-apps": { + display: "hidden", }, - changelog: { - title: "Changelog", + "tool-calling-intro": { + display: "hidden", }, - "-- Tool Registry": { - type: "separator", - title: "Tool Registry", + "tool-writing-basics": { + display: "hidden", }, - "registry-early-access": { - title: "Registry Early Access", + "tool-writing-reference": { + display: "hidden", }, - "-- Resources": { - type: "separator", - title: "Resources", + "triggers-section": { + display: "hidden", }, - "contact-us": { - title: Contact us, + vercelai: { + display: "hidden", }, - status: { - title: Status, - href: "https://status.arcade.dev/", + guides: { + display: "hidden", }, }; diff --git a/app/en/home/agentic-architecture/_meta.tsx b/app/en/home/agentic-architecture/_meta.tsx new file mode 100644 index 000000000..996c7ffd3 --- /dev/null +++ b/app/en/home/agentic-architecture/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "kinds-of-agents": "Kinds of agents", + "architecture-patterns": "Architecture Patterns", +}; diff --git a/app/en/home/agentic-architecture/architecture-patterns/_meta.tsx b/app/en/home/agentic-architecture/architecture-patterns/_meta.tsx new file mode 100644 index 000000000..ce3462a52 --- /dev/null +++ b/app/en/home/agentic-architecture/architecture-patterns/_meta.tsx @@ -0,0 +1,3 @@ +export default { + "supervisor-architecture": "Supervisor architecture", +}; diff --git a/app/en/home/agentic-architecture/architecture-patterns/page.mdx b/app/en/home/agentic-architecture/architecture-patterns/page.mdx new file mode 100644 index 000000000..86876ffb3 --- /dev/null +++ b/app/en/home/agentic-architecture/architecture-patterns/page.mdx @@ -0,0 +1,7 @@ +# architecture patterns + +Documentation for architecture patterns. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/architecture-patterns/supervisor-architecture/page.mdx b/app/en/home/agentic-architecture/architecture-patterns/supervisor-architecture/page.mdx new file mode 100644 index 000000000..c3d748224 --- /dev/null +++ b/app/en/home/agentic-architecture/architecture-patterns/supervisor-architecture/page.mdx @@ -0,0 +1,7 @@ +# supervisor architecture + +Documentation for supervisor architecture. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/kinds-of-agents/_meta.tsx b/app/en/home/agentic-architecture/kinds-of-agents/_meta.tsx new file mode 100644 index 000000000..cdd141983 --- /dev/null +++ b/app/en/home/agentic-architecture/kinds-of-agents/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "background-agents": "Background agents + secrets", + "agent-apps": "Agent apps + auth", +}; diff --git a/app/en/home/agentic-architecture/kinds-of-agents/agent-apps/page.mdx b/app/en/home/agentic-architecture/kinds-of-agents/agent-apps/page.mdx new file mode 100644 index 000000000..07883e217 --- /dev/null +++ b/app/en/home/agentic-architecture/kinds-of-agents/agent-apps/page.mdx @@ -0,0 +1,7 @@ +# agent apps + +Documentation for agent apps. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/kinds-of-agents/background-agents/page.mdx b/app/en/home/agentic-architecture/kinds-of-agents/background-agents/page.mdx new file mode 100644 index 000000000..d1dd1acb0 --- /dev/null +++ b/app/en/home/agentic-architecture/kinds-of-agents/background-agents/page.mdx @@ -0,0 +1,7 @@ +# background agents + +Documentation for background agents. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/kinds-of-agents/page.mdx b/app/en/home/agentic-architecture/kinds-of-agents/page.mdx new file mode 100644 index 000000000..6ccccae12 --- /dev/null +++ b/app/en/home/agentic-architecture/kinds-of-agents/page.mdx @@ -0,0 +1,7 @@ +# kinds of agents + +Documentation for kinds of agents. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/page.mdx b/app/en/home/agentic-architecture/page.mdx new file mode 100644 index 000000000..94b1bf23a --- /dev/null +++ b/app/en/home/agentic-architecture/page.mdx @@ -0,0 +1,7 @@ +# Agentic Architecture & Workflows + +Design and implement agentic architectures. + +## Overview + +Learn about different types of agents and architecture patterns. diff --git a/app/en/home/api/page.mdx b/app/en/home/api/page.mdx new file mode 100644 index 000000000..f2bfd3ae7 --- /dev/null +++ b/app/en/home/api/page.mdx @@ -0,0 +1,7 @@ +# API + +Complete API reference for Arcade. + +## Overview + +Explore all available endpoints and their usage. diff --git a/app/en/home/arcade-clients/page.mdx b/app/en/home/arcade-clients/page.mdx new file mode 100644 index 000000000..9264ed976 --- /dev/null +++ b/app/en/home/arcade-clients/page.mdx @@ -0,0 +1,7 @@ +# Arcade Clients + +Client libraries and SDKs for Arcade. + +## Overview + +Get started with Arcade client libraries in various programming languages. diff --git a/app/en/home/arcade-mcp/page.mdx b/app/en/home/arcade-mcp/page.mdx new file mode 100644 index 000000000..435b2d04b --- /dev/null +++ b/app/en/home/arcade-mcp/page.mdx @@ -0,0 +1,7 @@ +# Arcade MCP + +Model Context Protocol integration with Arcade. + +## Overview + +Learn how to use Arcade with MCP-compatible clients. diff --git a/app/en/home/auth-and-secrets/page.mdx b/app/en/home/auth-and-secrets/page.mdx new file mode 100644 index 000000000..e0fbd283e --- /dev/null +++ b/app/en/home/auth-and-secrets/page.mdx @@ -0,0 +1,7 @@ +# How do auth and secrets work? + +Learn about authentication and secret management in Arcade. + +## Overview + +Understand how to handle authentication and manage secrets securely. diff --git a/app/en/home/blog/page.mdx b/app/en/home/blog/page.mdx new file mode 100644 index 000000000..f0018edfe --- /dev/null +++ b/app/en/home/blog/page.mdx @@ -0,0 +1,7 @@ +# Blog + +Read the latest news and insights from the Arcade team. + +## Latest Posts + +Coming soon. \ No newline at end of file diff --git a/app/en/home/changelog-page/page.mdx b/app/en/home/changelog-page/page.mdx new file mode 100644 index 000000000..372070802 --- /dev/null +++ b/app/en/home/changelog-page/page.mdx @@ -0,0 +1,7 @@ +# Changelog + +Stay up to date with the latest changes and improvements to Arcade. + +## Recent Updates + +Documentation coming soon. \ No newline at end of file diff --git a/app/en/home/concepts/_meta.tsx b/app/en/home/concepts/_meta.tsx new file mode 100644 index 000000000..fe11ad060 --- /dev/null +++ b/app/en/home/concepts/_meta.tsx @@ -0,0 +1,6 @@ +export default { + index: { + display: "hidden", + }, + "tool-types": "Tool types", +}; diff --git a/app/en/home/concepts/page.mdx b/app/en/home/concepts/page.mdx new file mode 100644 index 000000000..009dc67b6 --- /dev/null +++ b/app/en/home/concepts/page.mdx @@ -0,0 +1,7 @@ +# Concepts + +Core concepts and principles of Arcade. + +## Overview + +Learn about fundamental concepts like tool types and more. \ No newline at end of file diff --git a/app/en/home/concepts/tool-types/page.mdx b/app/en/home/concepts/tool-types/page.mdx new file mode 100644 index 000000000..83dd82a47 --- /dev/null +++ b/app/en/home/concepts/tool-types/page.mdx @@ -0,0 +1,7 @@ +# Tool Types + +Learn about different types of tools in Arcade. + +## Overview + +Understand the various categories and types of tools available. \ No newline at end of file diff --git a/app/en/home/creating-tools/_meta.tsx b/app/en/home/creating-tools/_meta.tsx new file mode 100644 index 000000000..ad769b484 --- /dev/null +++ b/app/en/home/creating-tools/_meta.tsx @@ -0,0 +1,10 @@ +export default { + "tool-basics": "Tool building basics", + "performance-tools": + "Building tools to get more performance out of existing toolkits", + "new-functionality": + "Building tools with agent functionality that doesn't exist", + "newest-models": "Ensure tools work with the newest models", + "migrate-mcp": "Migrating tools to MCP servers", + "error-handling": "Error handling", +}; diff --git a/app/en/home/creating-tools/error-handling/page.mdx b/app/en/home/creating-tools/error-handling/page.mdx new file mode 100644 index 000000000..ac2f06ae8 --- /dev/null +++ b/app/en/home/creating-tools/error-handling/page.mdx @@ -0,0 +1,7 @@ +# error handling + +Documentation for error handling. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/creating-tools/migrate-mcp/page.mdx b/app/en/home/creating-tools/migrate-mcp/page.mdx new file mode 100644 index 000000000..5e0e84e4e --- /dev/null +++ b/app/en/home/creating-tools/migrate-mcp/page.mdx @@ -0,0 +1,7 @@ +# migrate mcp + +Documentation for migrate mcp. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/creating-tools/new-functionality/page.mdx b/app/en/home/creating-tools/new-functionality/page.mdx new file mode 100644 index 000000000..2a1c331e7 --- /dev/null +++ b/app/en/home/creating-tools/new-functionality/page.mdx @@ -0,0 +1,7 @@ +# new functionality + +Documentation for new functionality. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/creating-tools/newest-models/page.mdx b/app/en/home/creating-tools/newest-models/page.mdx new file mode 100644 index 000000000..1ee16c0fb --- /dev/null +++ b/app/en/home/creating-tools/newest-models/page.mdx @@ -0,0 +1,7 @@ +# newest models + +Documentation for newest models. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/creating-tools/page.mdx b/app/en/home/creating-tools/page.mdx new file mode 100644 index 000000000..7e602365f --- /dev/null +++ b/app/en/home/creating-tools/page.mdx @@ -0,0 +1,3 @@ +# Creating tools + +Learn how to create custom tools. \ No newline at end of file diff --git a/app/en/home/creating-tools/performance-tools/page.mdx b/app/en/home/creating-tools/performance-tools/page.mdx new file mode 100644 index 000000000..ce4e3f770 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/page.mdx @@ -0,0 +1,7 @@ +# performance tools + +Documentation for performance tools. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/creating-tools/tool-basics/page.mdx b/app/en/home/creating-tools/tool-basics/page.mdx new file mode 100644 index 000000000..bacdda8a3 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/page.mdx @@ -0,0 +1,7 @@ +# tool basics + +Documentation for tool basics. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/deployment-hosting/page.mdx b/app/en/home/deployment-hosting/page.mdx new file mode 100644 index 000000000..54d933cc3 --- /dev/null +++ b/app/en/home/deployment-hosting/page.mdx @@ -0,0 +1,7 @@ +# Deployment and Hosting + +Deploy and host your Arcade applications. + +## Overview + +Learn deployment strategies and hosting options. diff --git a/app/en/home/examples/page.mdx b/app/en/home/examples/page.mdx new file mode 100644 index 000000000..b9109387a --- /dev/null +++ b/app/en/home/examples/page.mdx @@ -0,0 +1,7 @@ +# Examples (tutorials and sample code) + +Practical tutorials and sample code for building with Arcade. + +## Overview + +Turn Confluence into Jira Tickets, create daily digests, and more. diff --git a/app/en/home/guides/_meta.tsx b/app/en/home/guides/_meta.tsx new file mode 100644 index 000000000..ff8b4c563 --- /dev/null +++ b/app/en/home/guides/_meta.tsx @@ -0,0 +1 @@ +export default {}; diff --git a/app/en/home/guides/page.mdx b/app/en/home/guides/page.mdx new file mode 100644 index 000000000..f03d92aef --- /dev/null +++ b/app/en/home/guides/page.mdx @@ -0,0 +1,7 @@ +# Guides + +Comprehensive guides for building with Arcade. + +## Overview + +Learn how to use tools, create tools, and set up authentication. diff --git a/app/en/home/orchestrators/page.mdx b/app/en/home/orchestrators/page.mdx new file mode 100644 index 000000000..cb2d4d627 --- /dev/null +++ b/app/en/home/orchestrators/page.mdx @@ -0,0 +1,7 @@ +# Orchestrators + +Learn about agent orchestration frameworks. + +## Overview + +Documentation for orchestrating multiple agents and workflows. diff --git a/app/en/home/quickstarts/_meta.tsx b/app/en/home/quickstarts/_meta.tsx new file mode 100644 index 000000000..cadbaf70b --- /dev/null +++ b/app/en/home/quickstarts/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "spin-up-server": "Spin up a server", + "call-tool-easy": "Call a tool (easiest possible)", + "call-tool-personal-agent": "Call a tool from your personal agent", +}; diff --git a/app/en/home/quickstarts/call-tool-easy/page.mdx b/app/en/home/quickstarts/call-tool-easy/page.mdx new file mode 100644 index 000000000..7def03e0c --- /dev/null +++ b/app/en/home/quickstarts/call-tool-easy/page.mdx @@ -0,0 +1,7 @@ +# Call a tool (easiest possible) + +The simplest way to call an Arcade tool. + +## Overview + +This is the easiest possible way to make your first tool call with Arcade. \ No newline at end of file diff --git a/app/en/home/quickstarts/call-tool-personal-agent/page.mdx b/app/en/home/quickstarts/call-tool-personal-agent/page.mdx new file mode 100644 index 000000000..b2c9a8e26 --- /dev/null +++ b/app/en/home/quickstarts/call-tool-personal-agent/page.mdx @@ -0,0 +1,7 @@ +# Call a tool from your personal agent + +Learn how to integrate Arcade tools with your personal AI agent. + +## Overview + +This guide shows you how to call Arcade tools from your personal agent setup. \ No newline at end of file diff --git a/app/en/home/quickstarts/page.mdx b/app/en/home/quickstarts/page.mdx new file mode 100644 index 000000000..c3196ce85 --- /dev/null +++ b/app/en/home/quickstarts/page.mdx @@ -0,0 +1,7 @@ +# Quickstarts + +Get started quickly with Arcade. + +## Overview + +Choose from these quickstart guides to begin using Arcade in different ways. \ No newline at end of file diff --git a/app/en/home/quickstarts/spin-up-server/page.mdx b/app/en/home/quickstarts/spin-up-server/page.mdx new file mode 100644 index 000000000..9ca9ff2ec --- /dev/null +++ b/app/en/home/quickstarts/spin-up-server/page.mdx @@ -0,0 +1,7 @@ +# Spin up a server + +Get started by spinning up an Arcade server in minutes. + +## Overview + +This quickstart guide will help you set up and run an Arcade server locally. \ No newline at end of file diff --git a/app/en/home/scaling/_meta.tsx b/app/en/home/scaling/_meta.tsx new file mode 100644 index 000000000..7d084135e --- /dev/null +++ b/app/en/home/scaling/_meta.tsx @@ -0,0 +1,3 @@ +export default { + "custom-auth": "Customizing Auth", +}; diff --git a/app/en/home/scaling/custom-auth/page.mdx b/app/en/home/scaling/custom-auth/page.mdx new file mode 100644 index 000000000..4b74fc3a9 --- /dev/null +++ b/app/en/home/scaling/custom-auth/page.mdx @@ -0,0 +1,7 @@ +# custom auth + +Documentation for custom auth. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/scaling/page.mdx b/app/en/home/scaling/page.mdx new file mode 100644 index 000000000..38b1b087b --- /dev/null +++ b/app/en/home/scaling/page.mdx @@ -0,0 +1,7 @@ +# Scaling + +Scale your Arcade applications to multiple users. + +## Overview + +Learn how to implement multi-user authentication and custom auth flows. diff --git a/app/en/home/security/page.mdx b/app/en/home/security/page.mdx new file mode 100644 index 000000000..7621354ee --- /dev/null +++ b/app/en/home/security/page.mdx @@ -0,0 +1,7 @@ +# Security + +Security best practices for Arcade applications. + +## Overview + +Learn about security considerations and best practices. diff --git a/app/en/home/setup/_meta.tsx b/app/en/home/setup/_meta.tsx new file mode 100644 index 000000000..78947cf62 --- /dev/null +++ b/app/en/home/setup/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "api-key": "API key", + "connect-arcade-docs": "Connect Arcade Docs to Your IDE", +}; diff --git a/app/en/home/setup/api-key/page.mdx b/app/en/home/setup/api-key/page.mdx new file mode 100644 index 000000000..6d342401b --- /dev/null +++ b/app/en/home/setup/api-key/page.mdx @@ -0,0 +1,7 @@ +# API Key + +Learn how to obtain and configure your API key for Arcade. + +## Overview + +This guide covers setting up your API key to start using Arcade services. \ No newline at end of file diff --git a/app/en/home/setup/connect-arcade-docs/page.mdx b/app/en/home/setup/connect-arcade-docs/page.mdx new file mode 100644 index 000000000..5ca76eeec --- /dev/null +++ b/app/en/home/setup/connect-arcade-docs/page.mdx @@ -0,0 +1,7 @@ +# Connect Arcade Docs to Your IDE + +Set up Arcade documentation integration with your development environment. + +## Overview + +This guide shows you how to connect Arcade documentation directly to your IDE for seamless development. \ No newline at end of file diff --git a/app/en/home/setup/page.mdx b/app/en/home/setup/page.mdx new file mode 100644 index 000000000..64fdc5761 --- /dev/null +++ b/app/en/home/setup/page.mdx @@ -0,0 +1,7 @@ +# Setup + +Set up your environment to start using Arcade. + +## Overview + +This section covers getting your API key and connecting Arcade documentation to your IDE. \ No newline at end of file diff --git a/app/en/home/status-page/page.mdx b/app/en/home/status-page/page.mdx new file mode 100644 index 000000000..25d2f5862 --- /dev/null +++ b/app/en/home/status-page/page.mdx @@ -0,0 +1,7 @@ +# Status + +View the current status of Arcade services. + +## Overview + +This page shows the current operational status of all Arcade services. \ No newline at end of file diff --git a/app/en/home/using-tools/_meta.tsx b/app/en/home/using-tools/_meta.tsx new file mode 100644 index 000000000..5e46ac883 --- /dev/null +++ b/app/en/home/using-tools/_meta.tsx @@ -0,0 +1,8 @@ +export default { + "third-party-apps": "Add tools to third party applications", + "custom-apps": "Add tools in custom applications", + triggers: "Triggers", + "agent-functionality": + "Building tools with agent functionality that doesn't exist", + "multi-user-auth": "Set-up secure multi-user auth for your app", +}; diff --git a/app/en/home/using-tools/agent-functionality/page.mdx b/app/en/home/using-tools/agent-functionality/page.mdx new file mode 100644 index 000000000..4fd175e26 --- /dev/null +++ b/app/en/home/using-tools/agent-functionality/page.mdx @@ -0,0 +1,7 @@ +# agent functionality + +Documentation for agent functionality. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/using-tools/custom-apps/page.mdx b/app/en/home/using-tools/custom-apps/page.mdx new file mode 100644 index 000000000..cfa0b7f37 --- /dev/null +++ b/app/en/home/using-tools/custom-apps/page.mdx @@ -0,0 +1,7 @@ +# custom apps + +Documentation for custom apps. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/using-tools/multi-user-auth/page.mdx b/app/en/home/using-tools/multi-user-auth/page.mdx new file mode 100644 index 000000000..6b55c7ec7 --- /dev/null +++ b/app/en/home/using-tools/multi-user-auth/page.mdx @@ -0,0 +1,7 @@ +# multi user auth + +Documentation for multi user auth. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/using-tools/page.mdx b/app/en/home/using-tools/page.mdx new file mode 100644 index 000000000..814899e3e --- /dev/null +++ b/app/en/home/using-tools/page.mdx @@ -0,0 +1,3 @@ +# Using tools + +Learn how to use tools in your applications. \ No newline at end of file diff --git a/app/en/home/using-tools/third-party-apps/page.mdx b/app/en/home/using-tools/third-party-apps/page.mdx new file mode 100644 index 000000000..877b12daa --- /dev/null +++ b/app/en/home/using-tools/third-party-apps/page.mdx @@ -0,0 +1,7 @@ +# third party apps + +Documentation for third party apps. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/using-tools/triggers/page.mdx b/app/en/home/using-tools/triggers/page.mdx new file mode 100644 index 000000000..5a92232c1 --- /dev/null +++ b/app/en/home/using-tools/triggers/page.mdx @@ -0,0 +1,7 @@ +# triggers + +Documentation for triggers. + +## Overview + +Content for this section coming soon. diff --git a/app/en/home/what-is-agent/page.mdx b/app/en/home/what-is-agent/page.mdx new file mode 100644 index 000000000..1416a9ae2 --- /dev/null +++ b/app/en/home/what-is-agent/page.mdx @@ -0,0 +1,7 @@ +# What's an agent? + +Learn the fundamentals of AI agents. + +## Overview + +Understand what agents are and how they work. diff --git a/app/en/home/why-agents-call-tools/page.mdx b/app/en/home/why-agents-call-tools/page.mdx new file mode 100644 index 000000000..7efa78eb0 --- /dev/null +++ b/app/en/home/why-agents-call-tools/page.mdx @@ -0,0 +1,7 @@ +# Why and how do agents call tools? + +Learn why agents need tools and how tool calling works. + +## Overview + +Understand the relationship between agents and tools. From 36c57c132e298cb7f7aacd32926ba4f213e2c3e7 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Wed, 10 Dec 2025 10:32:51 -0800 Subject: [PATCH 04/11] Restructure navigation sidebar to match design specification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit implements a complete restructuring of the Nextra documentation sidebar navigation to match the provided mockup specification. Key changes: Major Structural Changes: - Reorganized content into clear sections: Get Started, Example agents, Guides, Learn, Updates, APIs & SDKs - Renamed directories (using-tools → calling-tools, orchestrators → agent-frameworks, scaling → sharing-with-end-users) - Created proper hierarchical structures for all major sections Navigation Cleanup: - Removed duplicate navigation entries caused by page.mdx files in directories with subdirectories - Fixed auto-discovery issues by explicitly hiding unwanted directories - Eliminated "orchestrators" references and created clean agent-frameworks structure - Removed extra items like "Auth Providers", "Scaling", "migrate mcp" from various sections Section-Specific Improvements: - Calling tools: Organized into 3rd party apps, custom apps, triggers, and reference sections - Creating tools: Restructured into 7 major subsections with proper nesting - Deployment & Hosting: Converted from single link to proper subsection structure - Security & Compliance: Cleaned up to show only 3 specified items - Customizing Auth: Fixed order and removed duplicates, added OAuth 2.0 properly - Learn: Added proper subsections to "What's an agent?" and cleaned up duplicates - Arcade Clients: Removed duplicates and standardized to 3 clients Technical Implementation: - Updated all _meta.tsx files to match new structure - Created proper directory hierarchies with placeholder content - Added comprehensive hidden directory list to prevent auto-discovery issues - Maintained proper Nextra navigation patterns throughout 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- app/en/home/_meta.tsx | 89 +- app/en/home/about-arcade/page.mdx | 3 + app/en/home/add-external-mcp/page.mdx | 3 + app/en/home/agent-frameworks/_meta.tsx | 10 + app/en/home/agent-frameworks/crewai/_meta.tsx | 22 + .../crewai/custom-auth-flow/page.mdx | 234 ++++ .../crewai/quickstart-python/page.mdx | 7 + .../crewai/quickstart-typescript/page.mdx | 7 + .../agent-frameworks/google-adk/_meta.tsx | 4 + .../google-adk/quickstart-python/page.mdx | 7 + .../google-adk/quickstart-typescript/page.mdx | 7 + .../home/agent-frameworks/langchain/_meta.tsx | 5 + .../langchain/quickstart-python/page.mdx | 7 + .../langchain/quickstart-typescript/page.mdx | 7 + .../langchain/using-langgraph-tools/page.mdx | 7 + app/en/home/agent-frameworks/mastra/_meta.tsx | 16 + .../mastra/quickstart-typescript/page.mdx | 7 + .../agent-frameworks/oai-agents/_meta.tsx | 4 + .../oai-agents/quickstart-python/page.mdx | 7 + .../oai-agents/quickstart-typescript/page.mdx | 7 + .../agent-frameworks/open-agents/_meta.tsx | 3 + .../open-agents/quickstart-python/page.mdx | 7 + .../home/agent-frameworks/vanilla/_meta.tsx | 4 + .../vanilla/python-quickstart/page.mdx | 3 + .../vanilla/typescript-quickstart/page.mdx | 3 + .../home/agent-frameworks/vercelai/_meta.tsx | 3 + .../vercelai/quickstart-typescript/page.mdx | 7 + .../architecture-patterns/page.mdx | 7 - .../kinds-of-agents/page.mdx | 7 - app/en/home/agentic-architecture/page.mdx | 7 - app/en/home/arcade-clients/_meta.tsx | 5 + app/en/home/arcade-clients/go-client/page.mdx | 3 + .../javascript-typescript-client/page.mdx | 3 + app/en/home/arcade-clients/page.mdx | 7 - .../arcade-clients/python-client/page.mdx | 3 + app/en/home/build-custom-mcp/page.mdx | 3 + .../home/calling-tools-custom-apps/page.mdx | 20 - app/en/home/calling-tools/_meta.tsx | 33 + .../calling-tools/auth-status-check/page.mdx | 7 + .../authorized-tool-calling/page.mdx | 7 + .../calling-tools/background-agents/page.mdx | 7 + .../calling-tools-custom-apps/page.mdx | 3 + .../calling-tools/connect-arcade-llm/page.mdx | 7 + .../calling-tools/direct-api-call/page.mdx | 7 + .../ensure-consistent-evals/page.mdx | 7 + .../calling-tools/error-handling/page.mdx | 3 + .../calling-tools/evaluation-suite/page.mdx | 3 + .../mcp-clients}/_meta.tsx | 0 .../mcp-clients/claude-desktop/page.mdx | 42 + .../calling-tools/mcp-clients/cursor/page.mdx | 48 + .../mcp-clients/visual-studio-code/page.mdx | 42 + .../calling-tools/mcp-gateway-auth/page.mdx | 3 + app/en/home/calling-tools/overview/page.mdx | 5 + .../scheduled-executions/page.mdx | 7 + .../third-party-apps/page.mdx | 0 .../home/calling-tools/tool-formats/page.mdx | 7 + app/en/home/common-use-cases/_meta.tsx | 8 + .../add-external-mcp-servers/page.md | 1 + .../home/common-use-cases/build-agent/page.md | 3 + .../build-custom-mcp-server/page.md | 1 + .../turn-external-api-into-mcp-server/page.md | 1 + .../home/configure-arcade-section/_meta.tsx | 3 +- .../overview-updated/page.mdx | 7 - app/en/home/confluence-jira-example/page.mdx | 3 + app/en/home/creating-tools/_meta.tsx | 3 +- .../creating-tools/error-handling/_meta.tsx | 4 + .../creating-tools/error-handling/page.mdx | 7 - .../error-handling/retry-tools/page.mdx | 7 + .../useful-tool-errors/page.mdx | 7 + .../creating-tools/evaluating-tools/_meta.tsx | 5 + .../create-evaluation-suite/page.mdx | 3 + .../evaluating-tools/run-evaluations/page.mdx | 7 + .../evaluating-tools/why-evaluate/page.mdx | 7 + .../home/creating-tools/migrate-mcp/page.mdx | 7 - .../new-functionality/_meta.tsx | 4 + .../new-functionality/custom-toolkit/page.mdx | 7 + .../eval-new-functionality/page.mdx | 7 + .../creating-tools/new-functionality/page.mdx | 7 - .../creating-tools/newest-models/_meta.tsx | 4 + .../modify-tool-new-model/page.mdx | 7 + .../creating-tools/newest-models/page.mdx | 7 - .../newest-models/run-eval-new-model/page.mdx | 7 + app/en/home/creating-tools/page.mdx | 3 - .../performance-tools/_meta.tsx | 7 + .../custom-tool-improvements/page.mdx | 7 + .../eval-starter-tools/page.mdx | 7 + .../creating-tools/performance-tools/page.mdx | 7 - .../run-evaluations-2/page.mdx | 7 + .../performance-tools/types-of-tools/page.mdx | 7 + .../registry-early-access/page.mdx | 3 + .../home/creating-tools/tool-basics/_meta.tsx | 11 + .../tool-basics/build-mcp-server/page.mdx | 3 + .../tool-basics/call-tools-mcp/page.mdx | 7 + .../tool-basics/compare-server-types/page.mdx | 7 + .../tool-basics/create-tool-auth/page.mdx | 7 + .../tool-basics/create-tool-secrets/page.mdx | 7 + .../tool-basics/migrate-toolkits/page.mdx | 7 + .../tool-basics/organize-mcp-tools/page.mdx | 7 + .../home/creating-tools/tool-basics/page.mdx | 7 - .../tool-basics/runtime-data-access/page.mdx | 7 + .../tool-basics/when-build-tools/page.mdx | 7 + app/en/home/daily-digest-example/page.mdx | 3 + app/en/home/deployment-hosting/_meta.tsx | 9 + .../deployment-hosting/arcade-deploy/page.mdx | 3 + .../cloud-infrastructure/page.mdx | 3 + .../configure-engine/page.mdx | 3 + .../deployment-hosting/evals-cicd/page.mdx | 3 + .../oauth-provider/page.mdx | 3 + .../on-premise-mcp/page.mdx | 3 + .../home/deployment-hosting/overview/page.mdx | 3 + app/en/home/deployment-hosting/page.mdx | 7 - app/en/home/orchestrators/page.mdx | 7 - app/en/home/quickstarts/_meta.tsx | 6 +- app/en/home/quickstarts/page.mdx | 7 - .../home/quickstarts/spin-up-server/page.mdx | 7 - app/en/home/scaling/_meta.tsx | 3 - app/en/home/scaling/custom-auth/page.mdx | 7 - app/en/home/scaling/page.mdx | 7 - app/en/home/security-section/_meta.tsx | 1 - .../identity-providers/page.mdx | 7 - app/en/home/security-section/soc-2/page.mdx | 7 - app/en/home/setup/page.mdx | 7 - app/en/home/sharing-with-end-users/_meta.tsx | 4 + .../custom-auth/_meta.tsx | 32 + .../custom-auth/airtable/page.mdx | 302 ++++ .../custom-auth/asana/page.mdx | 307 +++++ .../custom-auth/atlassian/page.mdx | 182 +++ .../custom-auth/calendly/page.mdx | 272 ++++ .../custom-auth/clickup/page.mdx | 171 +++ .../custom-auth/discord/page.mdx | 183 +++ .../custom-auth/figma/page.mdx | 294 ++++ .../custom-auth/github/page.mdx | 1215 +++++++++++++++++ .../custom-auth/google/page.mdx | 258 ++++ .../custom-auth/hubspot/page.mdx | 304 +++++ .../custom-auth/linear/page.mdx | 288 ++++ .../custom-auth/linkedin/page.mdx | 275 ++++ .../custom-auth/mailchimp/page.mdx | 331 +++++ .../custom-auth/microsoft/page.mdx | 197 +++ .../custom-auth/miro/page.mdx | 298 ++++ .../custom-auth/notion/page.mdx | 178 +++ .../custom-auth/oauth2/page.mdx | 619 +++++++++ .../custom-auth/overview/page.mdx | 3 + .../custom-auth/pagerduty/page.mdx | 293 ++++ .../custom-auth/reddit/page.mdx | 184 +++ .../custom-auth/salesforce/page.mdx | 566 ++++++++ .../custom-auth/slack/page.mdx | 238 ++++ .../custom-auth/spotify/page.mdx | 188 +++ .../custom-auth/square/page.mdx | 304 +++++ .../custom-auth/ticktick/page.mdx | 320 +++++ .../custom-auth/twitch/page.mdx | 211 +++ .../custom-auth/x/page.mdx | 195 +++ .../custom-auth/zendesk/page.mdx | 223 +++ .../custom-auth/zoho/page.mdx | 357 +++++ .../custom-auth/zoom/page.mdx | 187 +++ .../multi-user-auth/page.mdx | 0 app/en/home/third-party-apps/_meta.tsx | 7 - .../evaluation-suite/page.mdx | 7 - .../claude-desktop/page.mdx | 7 - .../mcp-clients-section/cursor/page.mdx | 7 - .../visual-studio-code/page.mdx | 7 - .../mcp-gateway-auth/page.mdx | 7 - .../mcp-gateway-quickstart-2/page.mdx | 7 - app/en/home/turn-api-to-mcp/page.mdx | 3 + app/en/home/using-tools/_meta.tsx | 8 - .../using-tools/agent-functionality/page.mdx | 7 - app/en/home/using-tools/custom-apps/page.mdx | 7 - app/en/home/using-tools/page.mdx | 3 - app/en/home/using-tools/triggers/page.mdx | 7 - app/en/home/what-is-agent/_meta.tsx | 4 + .../home/what-is-agent/intro-to-tag/page.mdx | 3 + app/en/home/what-is-agent/page.mdx | 7 - .../why-agents-call-tools/page.mdx | 3 + 172 files changed, 9938 insertions(+), 300 deletions(-) create mode 100644 app/en/home/about-arcade/page.mdx create mode 100644 app/en/home/add-external-mcp/page.mdx create mode 100644 app/en/home/agent-frameworks/_meta.tsx create mode 100644 app/en/home/agent-frameworks/crewai/_meta.tsx create mode 100644 app/en/home/agent-frameworks/crewai/custom-auth-flow/page.mdx create mode 100644 app/en/home/agent-frameworks/crewai/quickstart-python/page.mdx create mode 100644 app/en/home/agent-frameworks/crewai/quickstart-typescript/page.mdx create mode 100644 app/en/home/agent-frameworks/google-adk/_meta.tsx create mode 100644 app/en/home/agent-frameworks/google-adk/quickstart-python/page.mdx create mode 100644 app/en/home/agent-frameworks/google-adk/quickstart-typescript/page.mdx create mode 100644 app/en/home/agent-frameworks/langchain/_meta.tsx create mode 100644 app/en/home/agent-frameworks/langchain/quickstart-python/page.mdx create mode 100644 app/en/home/agent-frameworks/langchain/quickstart-typescript/page.mdx create mode 100644 app/en/home/agent-frameworks/langchain/using-langgraph-tools/page.mdx create mode 100644 app/en/home/agent-frameworks/mastra/_meta.tsx create mode 100644 app/en/home/agent-frameworks/mastra/quickstart-typescript/page.mdx create mode 100644 app/en/home/agent-frameworks/oai-agents/_meta.tsx create mode 100644 app/en/home/agent-frameworks/oai-agents/quickstart-python/page.mdx create mode 100644 app/en/home/agent-frameworks/oai-agents/quickstart-typescript/page.mdx create mode 100644 app/en/home/agent-frameworks/open-agents/_meta.tsx create mode 100644 app/en/home/agent-frameworks/open-agents/quickstart-python/page.mdx create mode 100644 app/en/home/agent-frameworks/vanilla/_meta.tsx create mode 100644 app/en/home/agent-frameworks/vanilla/python-quickstart/page.mdx create mode 100644 app/en/home/agent-frameworks/vanilla/typescript-quickstart/page.mdx create mode 100644 app/en/home/agent-frameworks/vercelai/_meta.tsx create mode 100644 app/en/home/agent-frameworks/vercelai/quickstart-typescript/page.mdx delete mode 100644 app/en/home/agentic-architecture/architecture-patterns/page.mdx delete mode 100644 app/en/home/agentic-architecture/kinds-of-agents/page.mdx delete mode 100644 app/en/home/agentic-architecture/page.mdx create mode 100644 app/en/home/arcade-clients/_meta.tsx create mode 100644 app/en/home/arcade-clients/go-client/page.mdx create mode 100644 app/en/home/arcade-clients/javascript-typescript-client/page.mdx delete mode 100644 app/en/home/arcade-clients/page.mdx create mode 100644 app/en/home/arcade-clients/python-client/page.mdx create mode 100644 app/en/home/build-custom-mcp/page.mdx delete mode 100644 app/en/home/calling-tools-custom-apps/page.mdx create mode 100644 app/en/home/calling-tools/_meta.tsx create mode 100644 app/en/home/calling-tools/auth-status-check/page.mdx create mode 100644 app/en/home/calling-tools/authorized-tool-calling/page.mdx create mode 100644 app/en/home/calling-tools/background-agents/page.mdx create mode 100644 app/en/home/calling-tools/calling-tools-custom-apps/page.mdx create mode 100644 app/en/home/calling-tools/connect-arcade-llm/page.mdx create mode 100644 app/en/home/calling-tools/direct-api-call/page.mdx create mode 100644 app/en/home/calling-tools/ensure-consistent-evals/page.mdx create mode 100644 app/en/home/calling-tools/error-handling/page.mdx create mode 100644 app/en/home/calling-tools/evaluation-suite/page.mdx rename app/en/home/{third-party-apps/mcp-clients-section => calling-tools/mcp-clients}/_meta.tsx (100%) create mode 100644 app/en/home/calling-tools/mcp-clients/claude-desktop/page.mdx create mode 100644 app/en/home/calling-tools/mcp-clients/cursor/page.mdx create mode 100644 app/en/home/calling-tools/mcp-clients/visual-studio-code/page.mdx create mode 100644 app/en/home/calling-tools/mcp-gateway-auth/page.mdx create mode 100644 app/en/home/calling-tools/overview/page.mdx create mode 100644 app/en/home/calling-tools/scheduled-executions/page.mdx rename app/en/home/{using-tools => calling-tools}/third-party-apps/page.mdx (100%) create mode 100644 app/en/home/calling-tools/tool-formats/page.mdx create mode 100644 app/en/home/common-use-cases/_meta.tsx create mode 100644 app/en/home/common-use-cases/add-external-mcp-servers/page.md create mode 100644 app/en/home/common-use-cases/build-agent/page.md create mode 100644 app/en/home/common-use-cases/build-custom-mcp-server/page.md create mode 100644 app/en/home/common-use-cases/turn-external-api-into-mcp-server/page.md delete mode 100644 app/en/home/configure-arcade-section/overview-updated/page.mdx create mode 100644 app/en/home/confluence-jira-example/page.mdx create mode 100644 app/en/home/creating-tools/error-handling/_meta.tsx delete mode 100644 app/en/home/creating-tools/error-handling/page.mdx create mode 100644 app/en/home/creating-tools/error-handling/retry-tools/page.mdx create mode 100644 app/en/home/creating-tools/error-handling/useful-tool-errors/page.mdx create mode 100644 app/en/home/creating-tools/evaluating-tools/_meta.tsx create mode 100644 app/en/home/creating-tools/evaluating-tools/create-evaluation-suite/page.mdx create mode 100644 app/en/home/creating-tools/evaluating-tools/run-evaluations/page.mdx create mode 100644 app/en/home/creating-tools/evaluating-tools/why-evaluate/page.mdx delete mode 100644 app/en/home/creating-tools/migrate-mcp/page.mdx create mode 100644 app/en/home/creating-tools/new-functionality/_meta.tsx create mode 100644 app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx create mode 100644 app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx delete mode 100644 app/en/home/creating-tools/new-functionality/page.mdx create mode 100644 app/en/home/creating-tools/newest-models/_meta.tsx create mode 100644 app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx delete mode 100644 app/en/home/creating-tools/newest-models/page.mdx create mode 100644 app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx delete mode 100644 app/en/home/creating-tools/page.mdx create mode 100644 app/en/home/creating-tools/performance-tools/_meta.tsx create mode 100644 app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx create mode 100644 app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx delete mode 100644 app/en/home/creating-tools/performance-tools/page.mdx create mode 100644 app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx create mode 100644 app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx create mode 100644 app/en/home/creating-tools/registry-early-access/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/_meta.tsx create mode 100644 app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx delete mode 100644 app/en/home/creating-tools/tool-basics/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx create mode 100644 app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx create mode 100644 app/en/home/daily-digest-example/page.mdx create mode 100644 app/en/home/deployment-hosting/_meta.tsx create mode 100644 app/en/home/deployment-hosting/arcade-deploy/page.mdx create mode 100644 app/en/home/deployment-hosting/cloud-infrastructure/page.mdx create mode 100644 app/en/home/deployment-hosting/configure-engine/page.mdx create mode 100644 app/en/home/deployment-hosting/evals-cicd/page.mdx create mode 100644 app/en/home/deployment-hosting/oauth-provider/page.mdx create mode 100644 app/en/home/deployment-hosting/on-premise-mcp/page.mdx create mode 100644 app/en/home/deployment-hosting/overview/page.mdx delete mode 100644 app/en/home/deployment-hosting/page.mdx delete mode 100644 app/en/home/orchestrators/page.mdx delete mode 100644 app/en/home/quickstarts/page.mdx delete mode 100644 app/en/home/quickstarts/spin-up-server/page.mdx delete mode 100644 app/en/home/scaling/_meta.tsx delete mode 100644 app/en/home/scaling/custom-auth/page.mdx delete mode 100644 app/en/home/scaling/page.mdx delete mode 100644 app/en/home/security-section/identity-providers/page.mdx delete mode 100644 app/en/home/security-section/soc-2/page.mdx delete mode 100644 app/en/home/setup/page.mdx create mode 100644 app/en/home/sharing-with-end-users/_meta.tsx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/_meta.tsx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/airtable/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/asana/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/atlassian/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/calendly/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/clickup/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/discord/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/figma/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/github/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/google/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/hubspot/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/linear/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/linkedin/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/mailchimp/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/microsoft/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/miro/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/notion/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/oauth2/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/overview/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/pagerduty/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/reddit/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/salesforce/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/slack/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/spotify/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/square/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/ticktick/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/twitch/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/x/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/zendesk/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/zoho/page.mdx create mode 100644 app/en/home/sharing-with-end-users/custom-auth/zoom/page.mdx rename app/en/home/{using-tools => sharing-with-end-users}/multi-user-auth/page.mdx (100%) delete mode 100644 app/en/home/third-party-apps/_meta.tsx delete mode 100644 app/en/home/third-party-apps/evaluation-suite/page.mdx delete mode 100644 app/en/home/third-party-apps/mcp-clients-section/claude-desktop/page.mdx delete mode 100644 app/en/home/third-party-apps/mcp-clients-section/cursor/page.mdx delete mode 100644 app/en/home/third-party-apps/mcp-clients-section/visual-studio-code/page.mdx delete mode 100644 app/en/home/third-party-apps/mcp-gateway-auth/page.mdx delete mode 100644 app/en/home/third-party-apps/mcp-gateway-quickstart-2/page.mdx create mode 100644 app/en/home/turn-api-to-mcp/page.mdx delete mode 100644 app/en/home/using-tools/_meta.tsx delete mode 100644 app/en/home/using-tools/agent-functionality/page.mdx delete mode 100644 app/en/home/using-tools/custom-apps/page.mdx delete mode 100644 app/en/home/using-tools/page.mdx delete mode 100644 app/en/home/using-tools/triggers/page.mdx create mode 100644 app/en/home/what-is-agent/_meta.tsx create mode 100644 app/en/home/what-is-agent/intro-to-tag/page.mdx delete mode 100644 app/en/home/what-is-agent/page.mdx create mode 100644 app/en/home/what-is-agent/why-agents-call-tools/page.mdx diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index e4255551e..c617b446c 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -26,52 +26,57 @@ export const meta: MetaRecord = { copyPage: false, }, }, - "-- Updates": { - type: "separator", - title: "Updates", - }, - "status-page": "Status", - "changelog-page": "Changelog", - blog: "Blog", "-- Get Started": { type: "separator", title: "Get Started", }, + "about-arcade": "About Arcade", setup: "Setup", quickstarts: "Quickstarts", - "-- Build": { + "common-use-cases": "Common Use Cases", + glossary: "Glossary", + faq: "FAQ", + "-- Example agents": { type: "separator", - title: "Build", + title: "Example agents", }, - "using-tools": "Using tools", + "confluence-jira-example": + "Turn Confluence into Jira Tickets/Turn Google doc into Linear Tickets", + "daily-digest-example": + "Daily Digest: Summarize your Google Calendar / Email stuffs", + "-- Guides": { + type: "separator", + title: "Guides", + }, + "configure-arcade-section": "Configure Arcade", + "calling-tools": "Calling tools", "creating-tools": "Creating tools", - orchestrators: "Orchestrators", - scaling: "Scaling", - "agentic-architecture": "Agentic Architecture & Workflows", - examples: "Examples (tutorials and sample code)", + "agent-frameworks": "Agent Frameworks", + "sharing-with-end-users": "Sharing your agent with end-users", + "observability-platforms": "Observability Platforms", "deployment-hosting": "Deployment and Hosting", - security: "Security", + "security-section": "Security and Compliance", "-- Learn": { type: "separator", title: "Learn", }, "what-is-agent": "What's an agent?", - "why-agents-call-tools": "Why and how do agents call tools?", "auth-and-secrets": "How do auth and secrets work?", + "agentic-architecture": "Agentic Architectures & Workflows", + "-- Updates": { + type: "separator", + title: "Updates", + }, + "status-page": "Status", + "changelog-page": "Changelog", + blog: "Blog", "-- APIs & SDKs": { type: "separator", title: "APIs & SDKs", }, api: "API", - "arcade-mcp": "Arcade MCP", + "arcade-mcp": "Arcade MCP (MCP Server SDK)", "arcade-clients": "Arcade Clients", - "-- Resources": { - type: "separator", - title: "Resources", - }, - glossary: "Glossary", - faq: "FAQ", - concepts: "Concepts", // Hide auto-discovered directories "api-keys": { display: "hidden", @@ -79,15 +84,9 @@ export const meta: MetaRecord = { "auth-providers": { display: "hidden", }, - "calling-tools-custom-apps": { - display: "hidden", - }, changelog: { display: "hidden", }, - "configure-arcade-section": { - display: "hidden", - }, "contact-us": { display: "hidden", }, @@ -127,9 +126,6 @@ export const meta: MetaRecord = { "oai-agents": { display: "hidden", }, - "observability-platforms": { - display: "hidden", - }, "open-agents": { display: "hidden", }, @@ -142,12 +138,6 @@ export const meta: MetaRecord = { "sample-agents": { display: "hidden", }, - "security-section": { - display: "hidden", - }, - "third-party-apps": { - display: "hidden", - }, "tool-calling-intro": { display: "hidden", }, @@ -166,6 +156,27 @@ export const meta: MetaRecord = { guides: { display: "hidden", }, + "add-external-mcp": { + display: "hidden", + }, + "build-custom-mcp": { + display: "hidden", + }, + concepts: { + display: "hidden", + }, + examples: { + display: "hidden", + }, + security: { + display: "hidden", + }, + "turn-api-to-mcp": { + display: "hidden", + }, + "why-agents-call-tools": { + display: "hidden", + }, }; export default meta; diff --git a/app/en/home/about-arcade/page.mdx b/app/en/home/about-arcade/page.mdx new file mode 100644 index 000000000..c2edbc64b --- /dev/null +++ b/app/en/home/about-arcade/page.mdx @@ -0,0 +1,3 @@ +# About Arcade + +How Arcade helps developers build better AI agents. \ No newline at end of file diff --git a/app/en/home/add-external-mcp/page.mdx b/app/en/home/add-external-mcp/page.mdx new file mode 100644 index 000000000..265b51036 --- /dev/null +++ b/app/en/home/add-external-mcp/page.mdx @@ -0,0 +1,3 @@ +# Add external MCP Servers to Arcade + +Learn how to integrate external MCP servers with Arcade. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/_meta.tsx b/app/en/home/agent-frameworks/_meta.tsx new file mode 100644 index 000000000..67eb769d0 --- /dev/null +++ b/app/en/home/agent-frameworks/_meta.tsx @@ -0,0 +1,10 @@ +export default { + vanilla: "Vanilla", + langchain: "LangGraph", + "oai-agents": "OpenAI Agents", + crewai: "CrewAI", + "open-agents": "OpenAgents", + "google-adk": "Google ADK", + mastra: "Mastra", + vercelai: "Vercel AI", +}; diff --git a/app/en/home/agent-frameworks/crewai/_meta.tsx b/app/en/home/agent-frameworks/crewai/_meta.tsx new file mode 100644 index 000000000..74c33d663 --- /dev/null +++ b/app/en/home/agent-frameworks/crewai/_meta.tsx @@ -0,0 +1,22 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "*": { + theme: { + breadcrumb: true, + toc: true, + copyPage: true, + }, + }, + "quickstart-python": { + title: "Quickstart (Python)", + }, + "quickstart-typescript": { + title: "Quickstart (Typescript)", + }, + "custom-auth-flow": { + title: "Custom auth flow", + }, +}; + +export default meta; diff --git a/app/en/home/agent-frameworks/crewai/custom-auth-flow/page.mdx b/app/en/home/agent-frameworks/crewai/custom-auth-flow/page.mdx new file mode 100644 index 000000000..7f847a772 --- /dev/null +++ b/app/en/home/agent-frameworks/crewai/custom-auth-flow/page.mdx @@ -0,0 +1,234 @@ +--- +title: "Custom Auth Flow with CrewAI" +description: "Learn how to create a custom auth flow with CrewAI" +--- + +import { Steps, Callout } from "nextra/components"; +import ToggleContent from "@/app/_components/toggle-content"; + +## Custom Auth Flow with CrewAI + +In this guide, we will explore how to create a custom auth flow that will be performed before executing Arcade tools within your CrewAI agent team. + +The `ArcadeToolManager`'s built-in authorization and tool execution flows work well for many typical use cases. However, some scenarios call for a tailored approach. By implementing a custom auth flow, you gain flexibility in handling tool authorization. If your use case calls for a unique interface, additional approval steps, or specialized error handling, then this guide is for you. + + + +### Prerequisites + +- [Obtain an Arcade API key](/home/api-keys) + +### Set up your environment + +Install the required package, and ensure your environment variables are set with your Arcade and OpenAI API keys: + +```bash +pip install crewai-arcade +``` + +### Configure API keys + +Provide your Arcade and OpenAI API keys. You can store them in environment variables like so: + +```bash +export ARCADE_API_KEY="your_arcade_api_key" +export OPENAI_API_KEY="your_openai_api_key" +``` + +### Define your custom auth flow + +The custom auth flow defined in the following code snippet is a function that will be called whenever CrewAI needs to call a tool. + +```python +from typing import Any + +from crewai_arcade import ArcadeToolManager + +USER_ID = "{arcade_user_id}" + +def custom_auth_flow( + manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any] +) -> Any: + """Custom auth flow for the ArcadeToolManager + + This function is called when CrewAI needs to call a tool that requires authorization. + Authorization is handled before executing the tool. + This function overrides the ArcadeToolManager's default auth flow performed by ArcadeToolManager.authorize_tool + """ + # Get authorization status + auth_response = manager.authorize(tool_name, USER_ID) + + # If the user is not authorized for the tool, + # then we need to handle the authorization before executing the tool + if not manager.is_authorized(auth_response.id): + print(f"Authorization required for tool: '{tool_name}' with inputs:") + for input_name, input_value in tool_input.items(): + print(f" {input_name}: {input_value}") + # Handle authorization + print(f"\nTo authorize, visit: {auth_response.url}") + # Block until the user has completed the authorization + auth_response = manager.wait_for_auth(auth_response) + + # Ensure authorization completed successfully + if not manager.is_authorized(auth_response.id): + raise ValueError(f"Authorization failed for {tool_name}. URL: {auth_response.url}") + else: + print(f"Authorization already granted for tool: '{tool_name}' with inputs:") + for input_name, input_value in tool_input.items(): + print(f" {input_name}: {input_value}") + + +def tool_manager_callback(tool_manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any]) -> Any: + """Tool executor callback with custom auth flow for the ArcadeToolManager + + ArcadeToolManager's default executor handles authorization and tool execution. + This function overrides the default executor to handle authorization in a custom way and then executes the tool. + """ + custom_auth_flow(tool_manager, tool_name, **tool_input) + return tool_manager.execute_tool(USER_ID, tool_name, **tool_input) +``` + +### Get Arcade tools + +You can now provide the tool manager callback to the `ArcadeToolManager` upon initialization: + +```python +# Provide the tool manager callback to the ArcadeToolManager +manager = ArcadeToolManager(executor=tool_manager_callback) + +# Retrieve the provided tools and/or MCP Servers as CrewAI StructuredTools. +tools = manager.get_tools(tools=["Gmail.ListEmails"], toolkits=["Slack"]) +``` + +### Use tools in your CrewAI agent team + +Create a Crew that uses your tools with the custom auth flow. When the tool is called, your tool manager callback will be called to handle the authorization and then the tool will be executed. + +```python +from crewai import Agent, Crew, Task +from crewai.llm import LLM + +crew_agent = Agent( + role="Main Agent", + backstory="You are a helpful assistant", + goal="Help the user with their requests", + tools=tools, + allow_delegation=False, + verbose=True, + llm=LLM(model="gpt-4o"), +) + +task = Task( + description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", + expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", + agent=crew_agent, + tools=crew_agent.tools, +) + +crew = Crew( + agents=[crew_agent], + tasks=[task], + verbose=True, + memory=True, +) + +result = crew.kickoff() + +print("\n\n\n ------------ Result ------------ \n\n\n") +print(result) +``` + + + + + +```python +from typing import Any + +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from crewai_arcade import ArcadeToolManager + +USER_ID = "{arcade_user_id}" + +def custom_auth_flow( + manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any] +) -> Any: + """Custom auth flow for the ArcadeToolManager + + This function is called when CrewAI needs to call a tool that requires authorization. + Authorization is handled before executing the tool. + This function overrides the ArcadeToolManager's default auth flow performed by ArcadeToolManager.authorize_tool + """ + # Get authorization status + auth_response = manager.authorize(tool_name, USER_ID) + + # If the user is not authorized for the tool, + # then we need to handle the authorization before executing the tool + if not manager.is_authorized(auth_response.id): + print(f"Authorization required for tool: '{tool_name}' with inputs:") + for input_name, input_value in tool_input.items(): + print(f" {input_name}: {input_value}") + # Handle authorization + print(f"\nTo authorize, visit: {auth_response.url}") + # Block until the user has completed the authorization + auth_response = manager.wait_for_auth(auth_response) + + # Ensure authorization completed successfully + if not manager.is_authorized(auth_response.id): + raise ValueError(f"Authorization failed for {tool_name}. URL: {auth_response.url}") + else: + print(f"Authorization already granted for tool: '{tool_name}' with inputs:") + for input_name, input_value in tool_input.items(): + print(f" {input_name}: {input_value}") + + +def tool_manager_callback(tool_manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any]) -> Any: + """Tool executor callback with custom auth flow for the ArcadeToolManager + + ArcadeToolManager's default executor handles authorization and tool execution. + This function overrides the default executor to handle authorization in a custom way and then executes the tool. + """ + custom_auth_flow(tool_manager, tool_name, **tool_input) + return tool_manager.execute_tool(USER_ID, tool_name, **tool_input) + + +manager = ArcadeToolManager(executor=tool_manager_callback) + +tools = manager.get_tools(tools=["Gmail.ListEmails"], toolkits=["Slack"]) + +crew_agent = Agent( + role="Main Agent", + backstory="You are a helpful assistant", + goal="Help the user with their requests", + tools=tools, + allow_delegation=False, + verbose=True, + llm=LLM(model="gpt-4o"), +) + +task = Task( + description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", + expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", + agent=crew_agent, + tools=crew_agent.tools, +) + +crew = Crew( + agents=[crew_agent], + tasks=[task], + verbose=True, + memory=True, +) + +result = crew.kickoff() + +print("\n\n\n ------------ Result ------------ \n\n\n") +print(result) +``` + + + +## Next steps + +Now you're ready to integrate Arcade tools with a custom auth flow into your own CrewAI agent team. diff --git a/app/en/home/agent-frameworks/crewai/quickstart-python/page.mdx b/app/en/home/agent-frameworks/crewai/quickstart-python/page.mdx new file mode 100644 index 000000000..4b5421156 --- /dev/null +++ b/app/en/home/agent-frameworks/crewai/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using CrewAI with Python. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/crewai/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/crewai/quickstart-typescript/page.mdx new file mode 100644 index 000000000..92c76c387 --- /dev/null +++ b/app/en/home/agent-frameworks/crewai/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using CrewAI with TypeScript. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/google-adk/_meta.tsx b/app/en/home/agent-frameworks/google-adk/_meta.tsx new file mode 100644 index 000000000..e0b5f430e --- /dev/null +++ b/app/en/home/agent-frameworks/google-adk/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", +}; diff --git a/app/en/home/agent-frameworks/google-adk/quickstart-python/page.mdx b/app/en/home/agent-frameworks/google-adk/quickstart-python/page.mdx new file mode 100644 index 000000000..5f28a1305 --- /dev/null +++ b/app/en/home/agent-frameworks/google-adk/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Google ADK with Python. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/google-adk/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/google-adk/quickstart-typescript/page.mdx new file mode 100644 index 000000000..712d31c41 --- /dev/null +++ b/app/en/home/agent-frameworks/google-adk/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Google ADK with TypeScript. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/langchain/_meta.tsx b/app/en/home/agent-frameworks/langchain/_meta.tsx new file mode 100644 index 000000000..fb7cc7bbc --- /dev/null +++ b/app/en/home/agent-frameworks/langchain/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", + "using-langgraph-tools": "Using LangGraph tools", +}; diff --git a/app/en/home/agent-frameworks/langchain/quickstart-python/page.mdx b/app/en/home/agent-frameworks/langchain/quickstart-python/page.mdx new file mode 100644 index 000000000..e3c23b656 --- /dev/null +++ b/app/en/home/agent-frameworks/langchain/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph with Python. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/langchain/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/langchain/quickstart-typescript/page.mdx new file mode 100644 index 000000000..103d4694d --- /dev/null +++ b/app/en/home/agent-frameworks/langchain/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph with TypeScript. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/langchain/using-langgraph-tools/page.mdx b/app/en/home/agent-frameworks/langchain/using-langgraph-tools/page.mdx new file mode 100644 index 000000000..0bdf9a500 --- /dev/null +++ b/app/en/home/agent-frameworks/langchain/using-langgraph-tools/page.mdx @@ -0,0 +1,7 @@ +# Using LangGraph tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using LangGraph tools. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/mastra/_meta.tsx b/app/en/home/agent-frameworks/mastra/_meta.tsx new file mode 100644 index 000000000..5df9193ec --- /dev/null +++ b/app/en/home/agent-frameworks/mastra/_meta.tsx @@ -0,0 +1,16 @@ +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "*": { + theme: { + breadcrumb: true, + toc: true, + copyPage: true, + }, + }, + "quickstart-typescript": { + title: "Quickstart (Typescript)", + }, +}; + +export default meta; diff --git a/app/en/home/agent-frameworks/mastra/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/mastra/quickstart-typescript/page.mdx new file mode 100644 index 000000000..4d05ea8f5 --- /dev/null +++ b/app/en/home/agent-frameworks/mastra/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Mastra with TypeScript. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/oai-agents/_meta.tsx b/app/en/home/agent-frameworks/oai-agents/_meta.tsx new file mode 100644 index 000000000..e0b5f430e --- /dev/null +++ b/app/en/home/agent-frameworks/oai-agents/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "quickstart-python": "Quickstart (Python)", + "quickstart-typescript": "Quickstart (Typescript)", +}; diff --git a/app/en/home/agent-frameworks/oai-agents/quickstart-python/page.mdx b/app/en/home/agent-frameworks/oai-agents/quickstart-python/page.mdx new file mode 100644 index 000000000..2c7ba7b17 --- /dev/null +++ b/app/en/home/agent-frameworks/oai-agents/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAI Agents with Python. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/oai-agents/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/oai-agents/quickstart-typescript/page.mdx new file mode 100644 index 000000000..17a8cd8f1 --- /dev/null +++ b/app/en/home/agent-frameworks/oai-agents/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAI Agents with TypeScript. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/open-agents/_meta.tsx b/app/en/home/agent-frameworks/open-agents/_meta.tsx new file mode 100644 index 000000000..27ad4a394 --- /dev/null +++ b/app/en/home/agent-frameworks/open-agents/_meta.tsx @@ -0,0 +1,3 @@ +export default { + "quickstart-python": "Quickstart (Python)", +}; diff --git a/app/en/home/agent-frameworks/open-agents/quickstart-python/page.mdx b/app/en/home/agent-frameworks/open-agents/quickstart-python/page.mdx new file mode 100644 index 000000000..eb1d1c511 --- /dev/null +++ b/app/en/home/agent-frameworks/open-agents/quickstart-python/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Python) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using OpenAgents with Python. diff --git a/app/en/home/agent-frameworks/vanilla/_meta.tsx b/app/en/home/agent-frameworks/vanilla/_meta.tsx new file mode 100644 index 000000000..48bb45a29 --- /dev/null +++ b/app/en/home/agent-frameworks/vanilla/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "python-quickstart": "Python Quickstart", + "typescript-quickstart": "Typescript Quickstart", +}; diff --git a/app/en/home/agent-frameworks/vanilla/python-quickstart/page.mdx b/app/en/home/agent-frameworks/vanilla/python-quickstart/page.mdx new file mode 100644 index 000000000..6256d42f6 --- /dev/null +++ b/app/en/home/agent-frameworks/vanilla/python-quickstart/page.mdx @@ -0,0 +1,3 @@ +# Python Quickstart + +Get started with building vanilla Python agents using Arcade. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/vanilla/typescript-quickstart/page.mdx b/app/en/home/agent-frameworks/vanilla/typescript-quickstart/page.mdx new file mode 100644 index 000000000..2aeacee34 --- /dev/null +++ b/app/en/home/agent-frameworks/vanilla/typescript-quickstart/page.mdx @@ -0,0 +1,3 @@ +# Typescript Quickstart + +Get started with building vanilla TypeScript agents using Arcade. \ No newline at end of file diff --git a/app/en/home/agent-frameworks/vercelai/_meta.tsx b/app/en/home/agent-frameworks/vercelai/_meta.tsx new file mode 100644 index 000000000..c1d2a14cd --- /dev/null +++ b/app/en/home/agent-frameworks/vercelai/_meta.tsx @@ -0,0 +1,3 @@ +export default { + "quickstart-typescript": "Quickstart (Typescript)", +}; diff --git a/app/en/home/agent-frameworks/vercelai/quickstart-typescript/page.mdx b/app/en/home/agent-frameworks/vercelai/quickstart-typescript/page.mdx new file mode 100644 index 000000000..41312ce5a --- /dev/null +++ b/app/en/home/agent-frameworks/vercelai/quickstart-typescript/page.mdx @@ -0,0 +1,7 @@ +# Quickstart (Typescript) + +Documentation coming soon. + +## Overview + +This section will contain detailed information about using Vercel AI with TypeScript. \ No newline at end of file diff --git a/app/en/home/agentic-architecture/architecture-patterns/page.mdx b/app/en/home/agentic-architecture/architecture-patterns/page.mdx deleted file mode 100644 index 86876ffb3..000000000 --- a/app/en/home/agentic-architecture/architecture-patterns/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# architecture patterns - -Documentation for architecture patterns. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/kinds-of-agents/page.mdx b/app/en/home/agentic-architecture/kinds-of-agents/page.mdx deleted file mode 100644 index 6ccccae12..000000000 --- a/app/en/home/agentic-architecture/kinds-of-agents/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# kinds of agents - -Documentation for kinds of agents. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/agentic-architecture/page.mdx b/app/en/home/agentic-architecture/page.mdx deleted file mode 100644 index 94b1bf23a..000000000 --- a/app/en/home/agentic-architecture/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Agentic Architecture & Workflows - -Design and implement agentic architectures. - -## Overview - -Learn about different types of agents and architecture patterns. diff --git a/app/en/home/arcade-clients/_meta.tsx b/app/en/home/arcade-clients/_meta.tsx new file mode 100644 index 000000000..8afb6e990 --- /dev/null +++ b/app/en/home/arcade-clients/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "python-client": "Python Client", + "javascript-typescript-client": "JavaScript / TypeScript Client", + "go-client": "Go Client", +}; diff --git a/app/en/home/arcade-clients/go-client/page.mdx b/app/en/home/arcade-clients/go-client/page.mdx new file mode 100644 index 000000000..91e250a16 --- /dev/null +++ b/app/en/home/arcade-clients/go-client/page.mdx @@ -0,0 +1,3 @@ +# Go Client + +Arcade's Go client library for building agents. \ No newline at end of file diff --git a/app/en/home/arcade-clients/javascript-typescript-client/page.mdx b/app/en/home/arcade-clients/javascript-typescript-client/page.mdx new file mode 100644 index 000000000..7a94d1ac1 --- /dev/null +++ b/app/en/home/arcade-clients/javascript-typescript-client/page.mdx @@ -0,0 +1,3 @@ +# JavaScript / TypeScript Client + +Arcade's JavaScript/TypeScript client library for building agents. \ No newline at end of file diff --git a/app/en/home/arcade-clients/page.mdx b/app/en/home/arcade-clients/page.mdx deleted file mode 100644 index 9264ed976..000000000 --- a/app/en/home/arcade-clients/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Arcade Clients - -Client libraries and SDKs for Arcade. - -## Overview - -Get started with Arcade client libraries in various programming languages. diff --git a/app/en/home/arcade-clients/python-client/page.mdx b/app/en/home/arcade-clients/python-client/page.mdx new file mode 100644 index 000000000..bea1fefca --- /dev/null +++ b/app/en/home/arcade-clients/python-client/page.mdx @@ -0,0 +1,3 @@ +# Python Client + +Arcade's Python client library for building agents. \ No newline at end of file diff --git a/app/en/home/build-custom-mcp/page.mdx b/app/en/home/build-custom-mcp/page.mdx new file mode 100644 index 000000000..9de711c26 --- /dev/null +++ b/app/en/home/build-custom-mcp/page.mdx @@ -0,0 +1,3 @@ +# Build a custom MCP Server + +Create custom MCP servers that you or others can use in agents. \ No newline at end of file diff --git a/app/en/home/calling-tools-custom-apps/page.mdx b/app/en/home/calling-tools-custom-apps/page.mdx deleted file mode 100644 index ac2fb8f44..000000000 --- a/app/en/home/calling-tools-custom-apps/page.mdx +++ /dev/null @@ -1,20 +0,0 @@ -# Calling Tools in Your Custom Apps - -This is a placeholder page for calling tools in your custom applications. - -## Overview - -Learn how to integrate Arcade tools into your custom applications for enhanced functionality. - -## Key Concepts - -- Tool integration patterns -- Authentication handling -- Error management -- Performance optimization - -## Next Steps - -- [Get an API Key](/en/home/api-keys) -- [Tool Calling Introduction](/en/home/tool-calling-intro) -- [Connect Arcade tools to your LLM](/en/home/connect-arcade-llm) \ No newline at end of file diff --git a/app/en/home/calling-tools/_meta.tsx b/app/en/home/calling-tools/_meta.tsx new file mode 100644 index 000000000..90a46405b --- /dev/null +++ b/app/en/home/calling-tools/_meta.tsx @@ -0,0 +1,33 @@ +export default { + overview: "Overview", + "error-handling": "Error Handling", + "-- In 3rd party applications": { + type: "separator", + title: "In 3rd party applications", + }, + "third-party-apps": "Call a tool in your IDEs, MCP clients, or agents", + "mcp-clients": "Connecting to a MCP Client", + "evaluation-suite": "Creating an evaluation suite to test tools", + "mcp-gateway-auth": "Adding authentication to your MCP Gateway", + "-- In custom applications": { + type: "separator", + title: "In custom applications", + }, + "calling-tools-custom-apps": "Calling tools in your custom apps", + "authorized-tool-calling": "Authorized Tool Calling", + "auth-status-check": "Checking Authorization Status", + "tool-formats": "Tool formats", + "connect-arcade-llm": "Connecting Arcade tools to your LLM", + "ensure-consistent-evals": "Ensure consistent tool calls with evals", + "-- Triggers": { + type: "separator", + title: "Triggers", + }, + "background-agents": "Set up a background agent using events", + "scheduled-executions": "Set up scheduled tool executions", + "-- Reference": { + type: "separator", + title: "Reference", + }, + "direct-api-call": "Direct Third-Party API Call", +}; diff --git a/app/en/home/calling-tools/auth-status-check/page.mdx b/app/en/home/calling-tools/auth-status-check/page.mdx new file mode 100644 index 000000000..110951ac4 --- /dev/null +++ b/app/en/home/calling-tools/auth-status-check/page.mdx @@ -0,0 +1,7 @@ +# auth-status-check + +Documentation coming soon. + +## Overview + +This section will contain detailed information about auth-status-check. diff --git a/app/en/home/calling-tools/authorized-tool-calling/page.mdx b/app/en/home/calling-tools/authorized-tool-calling/page.mdx new file mode 100644 index 000000000..155ffc4a3 --- /dev/null +++ b/app/en/home/calling-tools/authorized-tool-calling/page.mdx @@ -0,0 +1,7 @@ +# authorized-tool-calling + +Documentation coming soon. + +## Overview + +This section will contain detailed information about authorized-tool-calling. diff --git a/app/en/home/calling-tools/background-agents/page.mdx b/app/en/home/calling-tools/background-agents/page.mdx new file mode 100644 index 000000000..dee52007f --- /dev/null +++ b/app/en/home/calling-tools/background-agents/page.mdx @@ -0,0 +1,7 @@ +# background-agents + +Documentation coming soon. + +## Overview + +This section will contain detailed information about background-agents. diff --git a/app/en/home/calling-tools/calling-tools-custom-apps/page.mdx b/app/en/home/calling-tools/calling-tools-custom-apps/page.mdx new file mode 100644 index 000000000..7540c8fbf --- /dev/null +++ b/app/en/home/calling-tools/calling-tools-custom-apps/page.mdx @@ -0,0 +1,3 @@ +# Calling tools in your custom apps + +Learn how to integrate and call tools within your custom applications. \ No newline at end of file diff --git a/app/en/home/calling-tools/connect-arcade-llm/page.mdx b/app/en/home/calling-tools/connect-arcade-llm/page.mdx new file mode 100644 index 000000000..49a1760ef --- /dev/null +++ b/app/en/home/calling-tools/connect-arcade-llm/page.mdx @@ -0,0 +1,7 @@ +# connect-arcade-llm + +Documentation coming soon. + +## Overview + +This section will contain detailed information about connect-arcade-llm. diff --git a/app/en/home/calling-tools/direct-api-call/page.mdx b/app/en/home/calling-tools/direct-api-call/page.mdx new file mode 100644 index 000000000..7f370bd51 --- /dev/null +++ b/app/en/home/calling-tools/direct-api-call/page.mdx @@ -0,0 +1,7 @@ +# direct-api-call + +Documentation coming soon. + +## Overview + +This section will contain detailed information about direct-api-call. diff --git a/app/en/home/calling-tools/ensure-consistent-evals/page.mdx b/app/en/home/calling-tools/ensure-consistent-evals/page.mdx new file mode 100644 index 000000000..160b83045 --- /dev/null +++ b/app/en/home/calling-tools/ensure-consistent-evals/page.mdx @@ -0,0 +1,7 @@ +# test-tool-performance + +Documentation coming soon. + +## Overview + +This section will contain detailed information about test-tool-performance. diff --git a/app/en/home/calling-tools/error-handling/page.mdx b/app/en/home/calling-tools/error-handling/page.mdx new file mode 100644 index 000000000..02d7882ce --- /dev/null +++ b/app/en/home/calling-tools/error-handling/page.mdx @@ -0,0 +1,3 @@ +# Error Handling + +Learn how to handle errors when using tools. \ No newline at end of file diff --git a/app/en/home/calling-tools/evaluation-suite/page.mdx b/app/en/home/calling-tools/evaluation-suite/page.mdx new file mode 100644 index 000000000..739dd71e5 --- /dev/null +++ b/app/en/home/calling-tools/evaluation-suite/page.mdx @@ -0,0 +1,3 @@ +# Creating an evaluation suite to test tools + +Learn how to create evaluation suites to test your tools effectively. \ No newline at end of file diff --git a/app/en/home/third-party-apps/mcp-clients-section/_meta.tsx b/app/en/home/calling-tools/mcp-clients/_meta.tsx similarity index 100% rename from app/en/home/third-party-apps/mcp-clients-section/_meta.tsx rename to app/en/home/calling-tools/mcp-clients/_meta.tsx diff --git a/app/en/home/calling-tools/mcp-clients/claude-desktop/page.mdx b/app/en/home/calling-tools/mcp-clients/claude-desktop/page.mdx new file mode 100644 index 000000000..3564263cd --- /dev/null +++ b/app/en/home/calling-tools/mcp-clients/claude-desktop/page.mdx @@ -0,0 +1,42 @@ +import { Steps, Tabs, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Use Arcade with Claude Desktop + +In this guide, you'll learn how to connect Claude Desktop to a local Arcade server. + + + +### Prerequisites + +1. Create an Arcade account +2. Get an [Arcade API key](/home/api-keys) +3. Create an [Arcade MCP Gateway](/home/mcp-gateways) and select the tools you want to use + +### Set up Claude Desktop + +1. Download and open [Claude Desktop](https://claude.ai/download) +2. Claude Menu --> "Settings" --> "Developer" --> "Edit Config" +3. Follow the guide [here](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) +4. Open the configuration file and replace the file contents with this: + * Give your MCP server a name, like `mcp-arcade` + * Use the the URL of your MCP Gateway. + * Add the API key as the bearer token within the `Authorization` header, and the email address that you used to sign up for the Arcade account as the `Arcade-User-ID` header + +```json +{ + "mcpServers": { + "arcade-mcp": { + "url": "https://api.arcade.dev/mcp/", + "headers": { + "Authorization": "Bearer {arcade_api_key}", + "Arcade-User-ID": "{arcade_user_id}" + } + } + } +} +``` + +5. Restart Claude Desktop. Upon restarting, you should have access to the Arcade tools you installed. + + diff --git a/app/en/home/calling-tools/mcp-clients/cursor/page.mdx b/app/en/home/calling-tools/mcp-clients/cursor/page.mdx new file mode 100644 index 000000000..d22dc925f --- /dev/null +++ b/app/en/home/calling-tools/mcp-clients/cursor/page.mdx @@ -0,0 +1,48 @@ +import { Steps, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + + +# Use Arcade in Cursor + +In this guide, you'll learn how to connect Cursor to an Arcade MCP Gateway. + + + +### Prerequisites + +1. Create an Arcade account +2. Get an [Arcade API key](/home/api-keys) +3. Create an [Arcade MCP Gateway](/home/mcp-gateways) and select the tools you want to use + +### Set up Cursor + +3. Download and open [Cursor](https://cursor.com/download) +4. Open the command palette and select **Open MCP Settings...** +5. Choose **HTTP** +6. Paste the URL of your MCP Gateway +7. Give your MCP server a name, like `mcp-arcade` +8. Add the API key as the bearer token within the `Authorization` header, and the email address that you used to sign up for the Arcade account as the `Arcade-User-ID` header + +Cursor will update your `settings.json` file with the following + +```json +{ + "mcpServers": { + "mcp-arcade": { + "url": "https://api.arcade.dev/mcp/", + "headers": { + "Authorization": "Bearer {arcade_api_key}", + "Arcade-User-ID": "{arcade_user_id}" + } + } + } +} +``` + +### Try it out + +1. Open the chat pane (typically command-l) +1. Make sure you are in **Agent** mode +1. Ask the agent to use a tool! + + diff --git a/app/en/home/calling-tools/mcp-clients/visual-studio-code/page.mdx b/app/en/home/calling-tools/mcp-clients/visual-studio-code/page.mdx new file mode 100644 index 000000000..bcb494226 --- /dev/null +++ b/app/en/home/calling-tools/mcp-clients/visual-studio-code/page.mdx @@ -0,0 +1,42 @@ +import { Steps, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Use Arcade in Visual Studio Code + +In this guide, you'll learn how to connect Visual Studio Code to an Arcade MCP Gateway. + + + +### Prerequisites + +1. Create an Arcade account +2. Get an [Arcade API key](/home/api-keys) +3. Create an [Arcade MCP Gateway](/home/mcp-gateways) and select the tools you want to use + +### Set up Visual Studio Code + +3. Download and open [Visual Studio Code](https://code.visualstudio.com/download) (version 1.100.0 or higher) +4. Open the command palette and select **MCP: Add Server...** +5. Choose **HTTP** +6. Paste the URL of your MCP Gateway. You may see a warning about Dynamic Client Registration. You can ignore this. +7. Give your MCP server a name, like `mcp-arcade` +8. Add the API key as the bearer token within the `Authorization` header, and the email address that you used to sign up for the Arcade account as the `Arcade-User-ID` header + +Visual Studio Code will update your `mcp.json` file, but you will manually need to add the headers above: + +```json +{ + "servers": { + "mcp-arcade": { + "url": "https://api.arcade.dev/mcp/", + "type": "http", + "headers": { + "Authorization": "Bearer {arcade_api_key}", + "Arcade-User-ID": "{arcade_user_id}" + } + } + } +} +``` + + diff --git a/app/en/home/calling-tools/mcp-gateway-auth/page.mdx b/app/en/home/calling-tools/mcp-gateway-auth/page.mdx new file mode 100644 index 000000000..68155fa2d --- /dev/null +++ b/app/en/home/calling-tools/mcp-gateway-auth/page.mdx @@ -0,0 +1,3 @@ +# Adding authentication to your MCP Gateway + +Learn how to add authentication to your MCP Gateway setup. \ No newline at end of file diff --git a/app/en/home/calling-tools/overview/page.mdx b/app/en/home/calling-tools/overview/page.mdx new file mode 100644 index 000000000..261ba2ccc --- /dev/null +++ b/app/en/home/calling-tools/overview/page.mdx @@ -0,0 +1,5 @@ +# Overview + +Core Concepts > Introduction + +Learn the fundamentals of using tools with Arcade. \ No newline at end of file diff --git a/app/en/home/calling-tools/scheduled-executions/page.mdx b/app/en/home/calling-tools/scheduled-executions/page.mdx new file mode 100644 index 000000000..c6116c323 --- /dev/null +++ b/app/en/home/calling-tools/scheduled-executions/page.mdx @@ -0,0 +1,7 @@ +# scheduled-executions + +Documentation coming soon. + +## Overview + +This section will contain detailed information about scheduled-executions. diff --git a/app/en/home/using-tools/third-party-apps/page.mdx b/app/en/home/calling-tools/third-party-apps/page.mdx similarity index 100% rename from app/en/home/using-tools/third-party-apps/page.mdx rename to app/en/home/calling-tools/third-party-apps/page.mdx diff --git a/app/en/home/calling-tools/tool-formats/page.mdx b/app/en/home/calling-tools/tool-formats/page.mdx new file mode 100644 index 000000000..b8dae2704 --- /dev/null +++ b/app/en/home/calling-tools/tool-formats/page.mdx @@ -0,0 +1,7 @@ +# tool-formats + +Documentation coming soon. + +## Overview + +This section will contain detailed information about tool-formats. diff --git a/app/en/home/common-use-cases/_meta.tsx b/app/en/home/common-use-cases/_meta.tsx new file mode 100644 index 000000000..82c3c4162 --- /dev/null +++ b/app/en/home/common-use-cases/_meta.tsx @@ -0,0 +1,8 @@ +export default { + "build-agent": "Build an agent that uses Arcade MCP Servers.", + "add-external-mcp-servers": "Add external MCP Servers to Arcade.", + "build-custom-mcp-server": + "Build a custom MCP Server. that you or others can put in your agent.", + "turn-external-api-into-mcp-server": + "Turn an external API into a MCP Server.", +}; diff --git a/app/en/home/common-use-cases/add-external-mcp-servers/page.md b/app/en/home/common-use-cases/add-external-mcp-servers/page.md new file mode 100644 index 000000000..51202cf18 --- /dev/null +++ b/app/en/home/common-use-cases/add-external-mcp-servers/page.md @@ -0,0 +1 @@ +Add external MCP Servers to Arcade. diff --git a/app/en/home/common-use-cases/build-agent/page.md b/app/en/home/common-use-cases/build-agent/page.md new file mode 100644 index 000000000..00eb54dfa --- /dev/null +++ b/app/en/home/common-use-cases/build-agent/page.md @@ -0,0 +1,3 @@ +# Common Use Cases + +Discover common ways developers use Arcade to build agents. diff --git a/app/en/home/common-use-cases/build-custom-mcp-server/page.md b/app/en/home/common-use-cases/build-custom-mcp-server/page.md new file mode 100644 index 000000000..d3a52658d --- /dev/null +++ b/app/en/home/common-use-cases/build-custom-mcp-server/page.md @@ -0,0 +1 @@ +build-custom-mcp-server diff --git a/app/en/home/common-use-cases/turn-external-api-into-mcp-server/page.md b/app/en/home/common-use-cases/turn-external-api-into-mcp-server/page.md new file mode 100644 index 000000000..b86be0987 --- /dev/null +++ b/app/en/home/common-use-cases/turn-external-api-into-mcp-server/page.md @@ -0,0 +1 @@ +turn-external-api-into-mcp-server diff --git a/app/en/home/configure-arcade-section/_meta.tsx b/app/en/home/configure-arcade-section/_meta.tsx index 152e60c03..23640a9ad 100644 --- a/app/en/home/configure-arcade-section/_meta.tsx +++ b/app/en/home/configure-arcade-section/_meta.tsx @@ -1,7 +1,6 @@ export default { - "overview-updated": "Overview", "dashboard-section": "Dashboard", - "create-tenants-section": "Create Tenants", + "create-tenants-section": "Create Organization", "create-projects-section": "Create Projects", "arcade-cli-section": "Using Arcade's CLI", }; diff --git a/app/en/home/configure-arcade-section/overview-updated/page.mdx b/app/en/home/configure-arcade-section/overview-updated/page.mdx deleted file mode 100644 index 3ab319f05..000000000 --- a/app/en/home/configure-arcade-section/overview-updated/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# overview-updated - -Documentation coming soon. - -## Overview - -This section will contain detailed information about overview-updated. diff --git a/app/en/home/confluence-jira-example/page.mdx b/app/en/home/confluence-jira-example/page.mdx new file mode 100644 index 000000000..360daf8d0 --- /dev/null +++ b/app/en/home/confluence-jira-example/page.mdx @@ -0,0 +1,3 @@ +# Turn Confluence into Jira Tickets/Turn Google doc into Linear Tickets + +Example agent that converts Confluence pages into Jira tickets or Google docs into Linear tickets. \ No newline at end of file diff --git a/app/en/home/creating-tools/_meta.tsx b/app/en/home/creating-tools/_meta.tsx index ad769b484..f096b94d6 100644 --- a/app/en/home/creating-tools/_meta.tsx +++ b/app/en/home/creating-tools/_meta.tsx @@ -1,10 +1,11 @@ export default { "tool-basics": "Tool building basics", + "evaluating-tools": "Evaluating tools", "performance-tools": "Building tools to get more performance out of existing toolkits", "new-functionality": "Building tools with agent functionality that doesn't exist", "newest-models": "Ensure tools work with the newest models", - "migrate-mcp": "Migrating tools to MCP servers", "error-handling": "Error handling", + "registry-early-access": "Registry Early Access", }; diff --git a/app/en/home/creating-tools/error-handling/_meta.tsx b/app/en/home/creating-tools/error-handling/_meta.tsx new file mode 100644 index 000000000..76b8981cc --- /dev/null +++ b/app/en/home/creating-tools/error-handling/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "useful-tool-errors": "Providing useful tool errors", + "retry-tools": "Retry tools with improved prompt", +}; diff --git a/app/en/home/creating-tools/error-handling/page.mdx b/app/en/home/creating-tools/error-handling/page.mdx deleted file mode 100644 index ac2f06ae8..000000000 --- a/app/en/home/creating-tools/error-handling/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# error handling - -Documentation for error handling. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/error-handling/retry-tools/page.mdx b/app/en/home/creating-tools/error-handling/retry-tools/page.mdx new file mode 100644 index 000000000..081f1c136 --- /dev/null +++ b/app/en/home/creating-tools/error-handling/retry-tools/page.mdx @@ -0,0 +1,7 @@ +# retry-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about retry-tools. diff --git a/app/en/home/creating-tools/error-handling/useful-tool-errors/page.mdx b/app/en/home/creating-tools/error-handling/useful-tool-errors/page.mdx new file mode 100644 index 000000000..c250ee99a --- /dev/null +++ b/app/en/home/creating-tools/error-handling/useful-tool-errors/page.mdx @@ -0,0 +1,7 @@ +# useful-tool-errors + +Documentation coming soon. + +## Overview + +This section will contain detailed information about useful-tool-errors. diff --git a/app/en/home/creating-tools/evaluating-tools/_meta.tsx b/app/en/home/creating-tools/evaluating-tools/_meta.tsx new file mode 100644 index 000000000..39a1896e7 --- /dev/null +++ b/app/en/home/creating-tools/evaluating-tools/_meta.tsx @@ -0,0 +1,5 @@ +export default { + "why-evaluate": "Why evaluate tools?", + "create-evaluation-suite": "Create an evaluation suite", + "run-evaluations": "Run evaluations", +}; diff --git a/app/en/home/creating-tools/evaluating-tools/create-evaluation-suite/page.mdx b/app/en/home/creating-tools/evaluating-tools/create-evaluation-suite/page.mdx new file mode 100644 index 000000000..93c71db16 --- /dev/null +++ b/app/en/home/creating-tools/evaluating-tools/create-evaluation-suite/page.mdx @@ -0,0 +1,3 @@ +# Create an evaluation suite + +Learn how to create evaluation suites for testing your tools. \ No newline at end of file diff --git a/app/en/home/creating-tools/evaluating-tools/run-evaluations/page.mdx b/app/en/home/creating-tools/evaluating-tools/run-evaluations/page.mdx new file mode 100644 index 000000000..ef0cdc212 --- /dev/null +++ b/app/en/home/creating-tools/evaluating-tools/run-evaluations/page.mdx @@ -0,0 +1,7 @@ +# run-evaluations + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-evaluations. diff --git a/app/en/home/creating-tools/evaluating-tools/why-evaluate/page.mdx b/app/en/home/creating-tools/evaluating-tools/why-evaluate/page.mdx new file mode 100644 index 000000000..da0906e4e --- /dev/null +++ b/app/en/home/creating-tools/evaluating-tools/why-evaluate/page.mdx @@ -0,0 +1,7 @@ +# why-evaluate + +Documentation coming soon. + +## Overview + +This section will contain detailed information about why-evaluate. diff --git a/app/en/home/creating-tools/migrate-mcp/page.mdx b/app/en/home/creating-tools/migrate-mcp/page.mdx deleted file mode 100644 index 5e0e84e4e..000000000 --- a/app/en/home/creating-tools/migrate-mcp/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# migrate mcp - -Documentation for migrate mcp. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/new-functionality/_meta.tsx b/app/en/home/creating-tools/new-functionality/_meta.tsx new file mode 100644 index 000000000..76bfd969c --- /dev/null +++ b/app/en/home/creating-tools/new-functionality/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "eval-new-functionality": "Write eval for functionality you want", + "custom-toolkit": "Write custom toolkit", +}; diff --git a/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx b/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx new file mode 100644 index 000000000..48d796c5a --- /dev/null +++ b/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx @@ -0,0 +1,7 @@ +# custom-toolkit + +Documentation coming soon. + +## Overview + +This section will contain detailed information about custom-toolkit. diff --git a/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx b/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx new file mode 100644 index 000000000..7acdc5dcb --- /dev/null +++ b/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx @@ -0,0 +1,7 @@ +# eval-new-functionality + +Documentation coming soon. + +## Overview + +This section will contain detailed information about eval-new-functionality. diff --git a/app/en/home/creating-tools/new-functionality/page.mdx b/app/en/home/creating-tools/new-functionality/page.mdx deleted file mode 100644 index 2a1c331e7..000000000 --- a/app/en/home/creating-tools/new-functionality/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# new functionality - -Documentation for new functionality. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/newest-models/_meta.tsx b/app/en/home/creating-tools/newest-models/_meta.tsx new file mode 100644 index 000000000..0bc71b765 --- /dev/null +++ b/app/en/home/creating-tools/newest-models/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "run-eval-new-model": "Run existing eval and observe outcome with new model", + "modify-tool-new-model": "Modify tool to work well with new model", +}; diff --git a/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx b/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx new file mode 100644 index 000000000..8cfa6e27f --- /dev/null +++ b/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx @@ -0,0 +1,7 @@ +# modify-tool-new-model + +Documentation coming soon. + +## Overview + +This section will contain detailed information about modify-tool-new-model. diff --git a/app/en/home/creating-tools/newest-models/page.mdx b/app/en/home/creating-tools/newest-models/page.mdx deleted file mode 100644 index 1ee16c0fb..000000000 --- a/app/en/home/creating-tools/newest-models/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# newest models - -Documentation for newest models. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx b/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx new file mode 100644 index 000000000..b29b2853e --- /dev/null +++ b/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx @@ -0,0 +1,7 @@ +# run-eval-new-model + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-eval-new-model. diff --git a/app/en/home/creating-tools/page.mdx b/app/en/home/creating-tools/page.mdx deleted file mode 100644 index 7e602365f..000000000 --- a/app/en/home/creating-tools/page.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Creating tools - -Learn how to create custom tools. \ No newline at end of file diff --git a/app/en/home/creating-tools/performance-tools/_meta.tsx b/app/en/home/creating-tools/performance-tools/_meta.tsx new file mode 100644 index 000000000..04730e0f9 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/_meta.tsx @@ -0,0 +1,7 @@ +export default { + "types-of-tools": "Types of tools", + "eval-starter-tools": "Write eval to assess combo of starter tools", + "custom-tool-improvements": + "Write custom tool that improves on relevant Starter tools", + "run-evaluations-2": "Run evaluations", +}; diff --git a/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx b/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx new file mode 100644 index 000000000..5ec9cca20 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx @@ -0,0 +1,7 @@ +# custom-tool-improvements + +Documentation coming soon. + +## Overview + +This section will contain detailed information about custom-tool-improvements. diff --git a/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx b/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx new file mode 100644 index 000000000..4df143348 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx @@ -0,0 +1,7 @@ +# eval-starter-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about eval-starter-tools. diff --git a/app/en/home/creating-tools/performance-tools/page.mdx b/app/en/home/creating-tools/performance-tools/page.mdx deleted file mode 100644 index ce4e3f770..000000000 --- a/app/en/home/creating-tools/performance-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# performance tools - -Documentation for performance tools. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx b/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx new file mode 100644 index 000000000..e3b7f1ae0 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx @@ -0,0 +1,7 @@ +# run-evaluations-2 + +Documentation coming soon. + +## Overview + +This section will contain detailed information about run-evaluations-2. diff --git a/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx b/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx new file mode 100644 index 000000000..f444c3598 --- /dev/null +++ b/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx @@ -0,0 +1,7 @@ +# types-of-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about types-of-tools. diff --git a/app/en/home/creating-tools/registry-early-access/page.mdx b/app/en/home/creating-tools/registry-early-access/page.mdx new file mode 100644 index 000000000..cd83c0b3c --- /dev/null +++ b/app/en/home/creating-tools/registry-early-access/page.mdx @@ -0,0 +1,3 @@ +# Registry Early Access + +Get early access to the Arcade tool registry. \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/_meta.tsx b/app/en/home/creating-tools/tool-basics/_meta.tsx new file mode 100644 index 000000000..16d64d3b8 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/_meta.tsx @@ -0,0 +1,11 @@ +export default { + "when-build-tools": "When to build tools", + "compare-server-types": "Compare Server Types", + "build-mcp-server": "Build MCP Server to write custom tools", + "create-tool-auth": "Create a tool with auth", + "create-tool-secrets": "Create a tool with secrets", + "runtime-data-access": "Accessing runtime data (Tools and Context)", + "call-tools-mcp": "Call tools from MCP clients", + "organize-mcp-tools": "Organize MCP server tools", + "migrate-toolkits": "Migrate from toolkits to MCP Servers", +}; diff --git a/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx b/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx new file mode 100644 index 000000000..0e691e68a --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx @@ -0,0 +1,3 @@ +# Build MCP Server to write custom tools + +Learn how to build an MCP server to write custom tools. \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx b/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx new file mode 100644 index 000000000..d5ecbbf58 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx @@ -0,0 +1,7 @@ +# call-tools-mcp + +Documentation coming soon. + +## Overview + +This section will contain detailed information about call-tools-mcp. diff --git a/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx b/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx new file mode 100644 index 000000000..580e3b3c1 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx @@ -0,0 +1,7 @@ +# compare-server-types + +Documentation coming soon. + +## Overview + +This section will contain detailed information about compare-server-types. diff --git a/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx b/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx new file mode 100644 index 000000000..412fb1902 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx @@ -0,0 +1,7 @@ +# create-tool-auth + +Documentation coming soon. + +## Overview + +This section will contain detailed information about create-tool-auth. diff --git a/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx b/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx new file mode 100644 index 000000000..27de627a4 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx @@ -0,0 +1,7 @@ +# create-tool-secrets + +Documentation coming soon. + +## Overview + +This section will contain detailed information about create-tool-secrets. diff --git a/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx b/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx new file mode 100644 index 000000000..e53ec9998 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx @@ -0,0 +1,7 @@ +# migrate-toolkits + +Documentation coming soon. + +## Overview + +This section will contain detailed information about migrate-toolkits. diff --git a/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx b/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx new file mode 100644 index 000000000..02a6fbf44 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx @@ -0,0 +1,7 @@ +# organize-mcp-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about organize-mcp-tools. diff --git a/app/en/home/creating-tools/tool-basics/page.mdx b/app/en/home/creating-tools/tool-basics/page.mdx deleted file mode 100644 index bacdda8a3..000000000 --- a/app/en/home/creating-tools/tool-basics/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# tool basics - -Documentation for tool basics. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx b/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx new file mode 100644 index 000000000..f35802fec --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx @@ -0,0 +1,7 @@ +# runtime-data-access + +Documentation coming soon. + +## Overview + +This section will contain detailed information about runtime-data-access. diff --git a/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx b/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx new file mode 100644 index 000000000..462900ed0 --- /dev/null +++ b/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx @@ -0,0 +1,7 @@ +# when-build-tools + +Documentation coming soon. + +## Overview + +This section will contain detailed information about when-build-tools. diff --git a/app/en/home/daily-digest-example/page.mdx b/app/en/home/daily-digest-example/page.mdx new file mode 100644 index 000000000..f7c9ff52a --- /dev/null +++ b/app/en/home/daily-digest-example/page.mdx @@ -0,0 +1,3 @@ +# Daily Digest: Summarize your Google Calendar / Email stuffs + +Example agent that creates daily digests from your Google Calendar and email. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/_meta.tsx b/app/en/home/deployment-hosting/_meta.tsx new file mode 100644 index 000000000..f7fe2ebae --- /dev/null +++ b/app/en/home/deployment-hosting/_meta.tsx @@ -0,0 +1,9 @@ +export default { + overview: "Overview", + "cloud-infrastructure": "Using Arcade's Cloud Infrastructure", + "on-premise-mcp": "Using On-premise MCP Servers", + "configure-engine": "Configure Arcade's Engine", + "oauth-provider": "Configure an OAuth provider", + "evals-cicd": "Set evals on CI/CD", + "arcade-deploy": "Arcade Deploy", +}; diff --git a/app/en/home/deployment-hosting/arcade-deploy/page.mdx b/app/en/home/deployment-hosting/arcade-deploy/page.mdx new file mode 100644 index 000000000..f47ca9390 --- /dev/null +++ b/app/en/home/deployment-hosting/arcade-deploy/page.mdx @@ -0,0 +1,3 @@ +# Arcade Deploy + +Deploy your applications using Arcade Deploy. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx b/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx new file mode 100644 index 000000000..4350b4f3f --- /dev/null +++ b/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx @@ -0,0 +1,3 @@ +# Using Arcade's Cloud Infrastructure + +Learn how to deploy using Arcade's cloud infrastructure. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/configure-engine/page.mdx b/app/en/home/deployment-hosting/configure-engine/page.mdx new file mode 100644 index 000000000..7d71200e9 --- /dev/null +++ b/app/en/home/deployment-hosting/configure-engine/page.mdx @@ -0,0 +1,3 @@ +# Configure Arcade's Engine + +How to configure Arcade's engine for your deployment. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/evals-cicd/page.mdx b/app/en/home/deployment-hosting/evals-cicd/page.mdx new file mode 100644 index 000000000..7adf44558 --- /dev/null +++ b/app/en/home/deployment-hosting/evals-cicd/page.mdx @@ -0,0 +1,3 @@ +# Set evals on CI/CD + +Configure evaluations in your CI/CD pipeline. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/oauth-provider/page.mdx b/app/en/home/deployment-hosting/oauth-provider/page.mdx new file mode 100644 index 000000000..f651e3000 --- /dev/null +++ b/app/en/home/deployment-hosting/oauth-provider/page.mdx @@ -0,0 +1,3 @@ +# Configure an OAuth provider + +Set up OAuth providers for your deployment. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/on-premise-mcp/page.mdx b/app/en/home/deployment-hosting/on-premise-mcp/page.mdx new file mode 100644 index 000000000..21ada0d3a --- /dev/null +++ b/app/en/home/deployment-hosting/on-premise-mcp/page.mdx @@ -0,0 +1,3 @@ +# Using On-premise MCP Servers + +Guide for using on-premise MCP servers. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/overview/page.mdx b/app/en/home/deployment-hosting/overview/page.mdx new file mode 100644 index 000000000..5fbceff45 --- /dev/null +++ b/app/en/home/deployment-hosting/overview/page.mdx @@ -0,0 +1,3 @@ +# Overview + +Overview of deployment and hosting options with Arcade. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/page.mdx b/app/en/home/deployment-hosting/page.mdx deleted file mode 100644 index 54d933cc3..000000000 --- a/app/en/home/deployment-hosting/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Deployment and Hosting - -Deploy and host your Arcade applications. - -## Overview - -Learn deployment strategies and hosting options. diff --git a/app/en/home/orchestrators/page.mdx b/app/en/home/orchestrators/page.mdx deleted file mode 100644 index cb2d4d627..000000000 --- a/app/en/home/orchestrators/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Orchestrators - -Learn about agent orchestration frameworks. - -## Overview - -Documentation for orchestrating multiple agents and workflows. diff --git a/app/en/home/quickstarts/_meta.tsx b/app/en/home/quickstarts/_meta.tsx index cadbaf70b..1bb896833 100644 --- a/app/en/home/quickstarts/_meta.tsx +++ b/app/en/home/quickstarts/_meta.tsx @@ -1,5 +1,5 @@ export default { - "spin-up-server": "Spin up a server", - "call-tool-easy": "Call a tool (easiest possible)", - "call-tool-personal-agent": "Call a tool from your personal agent", + "call-tool-easy": "Call a tool in your agent", + "call-tool-personal-agent": + "Call a tool in your IDEs, MCP clients, or agents", }; diff --git a/app/en/home/quickstarts/page.mdx b/app/en/home/quickstarts/page.mdx deleted file mode 100644 index c3196ce85..000000000 --- a/app/en/home/quickstarts/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstarts - -Get started quickly with Arcade. - -## Overview - -Choose from these quickstart guides to begin using Arcade in different ways. \ No newline at end of file diff --git a/app/en/home/quickstarts/spin-up-server/page.mdx b/app/en/home/quickstarts/spin-up-server/page.mdx deleted file mode 100644 index 9ca9ff2ec..000000000 --- a/app/en/home/quickstarts/spin-up-server/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Spin up a server - -Get started by spinning up an Arcade server in minutes. - -## Overview - -This quickstart guide will help you set up and run an Arcade server locally. \ No newline at end of file diff --git a/app/en/home/scaling/_meta.tsx b/app/en/home/scaling/_meta.tsx deleted file mode 100644 index 7d084135e..000000000 --- a/app/en/home/scaling/_meta.tsx +++ /dev/null @@ -1,3 +0,0 @@ -export default { - "custom-auth": "Customizing Auth", -}; diff --git a/app/en/home/scaling/custom-auth/page.mdx b/app/en/home/scaling/custom-auth/page.mdx deleted file mode 100644 index 4b74fc3a9..000000000 --- a/app/en/home/scaling/custom-auth/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# custom auth - -Documentation for custom auth. - -## Overview - -Content for this section coming soon. diff --git a/app/en/home/scaling/page.mdx b/app/en/home/scaling/page.mdx deleted file mode 100644 index 38b1b087b..000000000 --- a/app/en/home/scaling/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Scaling - -Scale your Arcade applications to multiple users. - -## Overview - -Learn how to implement multi-user authentication and custom auth flows. diff --git a/app/en/home/security-section/_meta.tsx b/app/en/home/security-section/_meta.tsx index ed097de59..ec6d02747 100644 --- a/app/en/home/security-section/_meta.tsx +++ b/app/en/home/security-section/_meta.tsx @@ -1,5 +1,4 @@ export default { - "identity-providers": "Supported Identity Providers", "platform-security": "Platform Security", "enterprise-sso": "Enterprise Single Sign On", "rbac-config": "Configuring Role Based Access Control for your organization", diff --git a/app/en/home/security-section/identity-providers/page.mdx b/app/en/home/security-section/identity-providers/page.mdx deleted file mode 100644 index 68db0a481..000000000 --- a/app/en/home/security-section/identity-providers/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# identity-providers - -Documentation coming soon. - -## Overview - -This section will contain detailed information about identity-providers. diff --git a/app/en/home/security-section/soc-2/page.mdx b/app/en/home/security-section/soc-2/page.mdx deleted file mode 100644 index 09f76374e..000000000 --- a/app/en/home/security-section/soc-2/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# soc-2 - -Documentation coming soon. - -## Overview - -This section will contain detailed information about soc-2. diff --git a/app/en/home/setup/page.mdx b/app/en/home/setup/page.mdx deleted file mode 100644 index 64fdc5761..000000000 --- a/app/en/home/setup/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Setup - -Set up your environment to start using Arcade. - -## Overview - -This section covers getting your API key and connecting Arcade documentation to your IDE. \ No newline at end of file diff --git a/app/en/home/sharing-with-end-users/_meta.tsx b/app/en/home/sharing-with-end-users/_meta.tsx new file mode 100644 index 000000000..4d1259dce --- /dev/null +++ b/app/en/home/sharing-with-end-users/_meta.tsx @@ -0,0 +1,4 @@ +export default { + "multi-user-auth": "Set-up secure multi-user auth for your app", + "custom-auth": "Customizing Auth", +}; diff --git a/app/en/home/sharing-with-end-users/custom-auth/_meta.tsx b/app/en/home/sharing-with-end-users/custom-auth/_meta.tsx new file mode 100644 index 000000000..3cc51dc10 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/_meta.tsx @@ -0,0 +1,32 @@ +export default { + overview: "Overview", + oauth2: "OAuth 2.0", + airtable: "Airtable", + asana: "Asana", + atlassian: "Atlassian", + calendly: "Calendly", + clickup: "ClickUp", + discord: "Discord", + figma: "Figma", + github: "GitHub", + google: "Google", + hubspot: "Hubspot", + linear: "Linear", + linkedin: "LinkedIn", + mailchimp: "Mailchimp", + microsoft: "Microsoft", + miro: "Miro", + notion: "Notion", + pagerduty: "PagerDuty", + reddit: "Reddit", + salesforce: "Salesforce", + slack: "Slack", + spotify: "Spotify", + square: "Square", + ticktick: "TickTick", + twitch: "Twitch", + x: "X", + zendesk: "Zendesk", + zoho: "Zoho", + zoom: "Zoom", +}; diff --git a/app/en/home/sharing-with-end-users/custom-auth/airtable/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/airtable/page.mdx new file mode 100644 index 000000000..7c58a9d75 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/airtable/page.mdx @@ -0,0 +1,302 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Airtable + +The Airtable auth provider enables tools and agents to call [Airtable APIs](https://airtable.com/developers/web/api/introduction) on behalf of a user using OAuth 2.0 authentication. + + + Want to quickly get started with Airtable in your agent or AI app? The pre-built + [Arcade Airtable MCP Server](/mcp-servers/productivity/airtable-api) is what you + want! + + +### What's documented here + +This page describes how to use and configure Airtable auth with Arcade. + +This auth provider is used by: + +- The [Arcade Airtable MCP Server](/mcp-servers/productivity/airtable-api), which provides pre-built tools for interacting with Airtable +- Your [app code](#using-airtable-auth-in-app-code) that needs to call the Airtable API +- Or, your [custom tools](#using-airtable-auth-in-custom-tools) that need to call the Airtable API + +## Configuring Airtable auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Airtable app credentials. This way, your users will see your application's name requesting permission. + +Before showing how to configure your Airtable app credentials, let's go through the steps to create an Airtable app. + +### Create an Airtable app + +To integrate with Airtable's API, you'll need to create an OAuth integration: + + + +#### Access the Airtable Developer Hub + +Navigate to the [Airtable Developer Hub](https://airtable.com/developers/web) and sign in with your Airtable account. + +#### Create a new OAuth integration + +1. Go to the [Create OAuth Integration](https://airtable.com/create/oauth) page +2. Fill in the required details: + - **Integration Name**: Choose a descriptive name for your application + - **Description**: Provide a brief description of your app's purpose + +#### Configure OAuth settings + +1. Set the **Redirect URL** to the redirect URL generated by Arcade (see configuration section below) +2. Configure the required **Scopes** for your application: + - `data.records:read` - Read records from tables + - `data.records:write` - Create, update, and delete records + - `schema.bases:read` - Read base schema + - Add other scopes as needed for your use case + +#### Obtain your credentials + +1. After creating your integration, you'll receive a **Client ID** +2. Generate a **Client Secret** from your integration settings +3. Copy both values for use in Arcade configuration + + + +For detailed instructions, refer to Airtable's [OAuth documentation](https://airtable.com/developers/web/guides/oauth-integrations). + +Next, add the Airtable app to Arcade. + +## Configuring your own Airtable Auth Provider in Arcade + + + + +### Configure Airtable Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **OAuth** section of the Arcade Dashboard left-side menu, click **Providers**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **OAuth 2.0** tab at the top. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "arcade-airtable"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Airtable integration. +- Configure the OAuth 2.0 endpoints: + - **Authorization URL**: `https://airtable.com/oauth2/v1/authorize` + - **Token URL**: `https://airtable.com/oauth2/v1/token` +- Note the **Redirect URL** generated by Arcade. This must be set as your Airtable integration's Redirect URL. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + + + + + +### Configure Airtable Auth Using Configuration File + + + This method is only available when you are [self-hosting the + engine](/home/deployment/on-prem-mcp) + + + + +#### Set environment variables + +Set the following environment variables: + +```bash +export AIRTABLE_CLIENT_ID="" +export AIRTABLE_CLIENT_SECRET="" +``` + +Or, you can set these values in a `.env` file: + +```bash +AIRTABLE_CLIENT_ID="" +AIRTABLE_CLIENT_SECRET="" +``` + +#### Edit the Engine configuration + +Edit the `engine.yaml` file and add a new item to the `auth.providers` section: + +```yaml +auth: + providers: + - id: arcade-airtable + description: Airtable OAuth 2.0 provider + enabled: true + type: oauth2 + client_id: ${env:AIRTABLE_CLIENT_ID} + client_secret: ${env:AIRTABLE_CLIENT_SECRET} + oauth2: + scope_delimiter: " " + pkce: + enabled: true + code_challenge_method: S256 + authorize_request: + endpoint: "https://airtable.com/oauth2/v1/authorize" + params: + response_type: code + client_id: "{{client_id}}" + redirect_uri: "{{redirect_uri}}" + scope: "{{scopes}}" + state: "{{state}}" + token_request: + endpoint: "https://airtable.com/oauth2/v1/token" + params: + grant_type: authorization_code + client_id: "{{client_id}}" + redirect_uri: "{{redirect_uri}}" + response_content_type: application/json +``` + + + + + + +When you use tools that require Airtable auth using your Arcade account credentials, Arcade will automatically use this Airtable OAuth provider. If you have multiple Airtable providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + +## Using Airtable auth in app code + +Use the Airtable auth provider in your own agents and AI apps to get a user token for the Airtable API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Airtable API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="arcade-airtable", + scopes=["data.records:read", "data.records:write", "schema.bases:read"] +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-11} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start( + userId, + "arcade-airtable", + ["data.records:read", "data.records:write", "schema.bases:read"] +); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Airtable auth in custom tools + +You can use the pre-built [Arcade Airtable MCP Server](/mcp-servers/productivity/airtable-api) to quickly build agents and AI apps that interact with Airtable. + +If the pre-built tools in the Airtable MCP Server don't meet your needs, you can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Airtable API. + +Use the `OAuth2()` auth class to specify that a tool requires authorization with Airtable. The `context.authorization.token` field will be automatically populated with the user's Airtable token: + +```python {8-12,22} +from typing import Annotated + +import httpx +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import OAuth2 + + +@tool( + requires_auth=OAuth2( + provider_id="arcade-airtable", + scopes=["data.records:read", "schema.bases:read"] + ) +) +async def list_bases( + context: ToolContext, +) -> Annotated[dict, "The user's bases."]: + """ + Retrieve the list of bases accessible to the authenticated user. + """ + url = "https://api.airtable.com/v0/meta/bases" + headers = { + "Authorization": context.authorization.token, + } + + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers) + response.raise_for_status() + return dict(response.json()) +``` + +## Available Scopes + +Airtable supports various OAuth scopes that determine the level of access your application has: + +- `data.records:read` - Read records from tables +- `data.records:write` - Create, update, and delete records +- `data.recordComments:read` - Read comments on records +- `data.recordComments:write` - Create and update comments on records +- `schema.bases:read` - Read base schema information +- `schema.bases:write` - Modify base schema +- `webhook:manage` - Create and manage webhooks +- `user.email:read` - Read user email address + +For a complete list of available scopes, refer to the [Airtable Scopes documentation](https://airtable.com/developers/web/api/scopes). + diff --git a/app/en/home/sharing-with-end-users/custom-auth/asana/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/asana/page.mdx new file mode 100644 index 000000000..62eb9c257 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/asana/page.mdx @@ -0,0 +1,307 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Asana + +The Asana auth provider enables tools and agents to call Asana APIs on behalf of a user. + + + Want to quickly get started with Asana services in your agent or AI app? The + pre-built [Arcade Asana MCP Server](/mcp-servers/productivity/asana) is what you + want! + + +## What's documented here + +This page describes how to use and configure Asana auth with Arcade. + +This auth provider is used by: + +- The [Arcade Asana MCP Server](/mcp-servers/productivity/asana), which provides pre-built tools for interacting with Asana +- Your [app code](#using-asana-auth-in-app-code) that needs to call Asana APIs +- Or, your [custom tools](#using-asana-auth-in-custom-tools) that need to call Asana APIs + +## Use Arcade's Default Asana Auth Provider + +Arcade offers a default Asana auth provider that you can use in the Arcade Cloud Platform. In this case, your users will see `Arcade` as the name of the application that's requesting permission. + +If you choose to use Arcade's Asana auth, you don't need to configure anything. Follow the [Asana MCP Server examples](/mcp-servers/productivity/asana) to get started calling Asana tools. + +## Use Your Own Asana App Credentials + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Asana app credentials. This way, your users will see your application's name requesting permission. + + +Before showing how to configure your Asana app credentials, let's go through the steps to create an Asana app. + +## Create an Asana App + +Follow the documentation on [Building an App with Asana](https://developers.asana.com/docs/overview). You may create a [developer sandbox account](https://developers.asana.com/docs/developer-sandbox) to test your app before moving to production. + +When creating your app, use the following settings: + +- Set an appropriate App name, description and icon. This will be visible to your users authorizing access to your app. +- Take note of the **Client ID** and **Client Secret**. +- In the OAuth settings: + - Under "Redirect URLs", click **Add Redirect URL** and add the redirect URL generated by Arcade (see below). + - Under "Permission Scopes", select "Full Permissions" +- In the "App Listing Details" section, optionally add more information about your app. +- In the "Manage Distribution" section, under "Choose a distribution method", select "Any workspace". +- Optionally, submit your app for the Asana team review. + + + Asana [recently + introduced](https://forum.asana.com/t/new-oauth-permission-scopes/1048556) + granular permission scopes. This feature is still in preview and the scopes + available at the moment do not include all endpoints/actions that the Asana + MCP Servers needs. For those reasons, Arcade uses the "Full Permissions" + scope. + + +## Configuring your own Asana Auth Provider in Arcade + + + + + +### Configure Asana Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **Asana**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-asana-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Asana app. +- Note the **Redirect URL** generated by Arcade. This must be added to your Asana app's Redirect URLs. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + +When you use tools that require Asana auth using your Arcade account credentials, Arcade will automatically use this Asana OAuth provider. If you have multiple Asana providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + + +## Using the Arcade Asana MCP Servers + +The [Arcade Asana MCP Server](/mcp-servers/productivity/asana) provides tools to interact with various Asana objects, such as tasks, projects, teams, and users. + +Refer to the [MCP Server documentation and examples](/mcp-servers/productivity/asana) to learn how to use the MCP Server to build agents and AI apps that interact with Asana services. + +## Using Asana auth in app code + +Use the Asana auth provider in your own agents and AI apps to get a user-scoped token for the Asana API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Asana API: + + + As explained [above](#create-an-asana-app), the Asana granular permission + scopes are in preview and not yet supported. The `"default"` scope should be + used to authorize any action/endpoint you need to call in the Asana API. + + + + + + +```python {21-22} +from arcadepy import Arcade + +client = Arcade(base_url="https://api.arcade.dev") # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="asana", + scopes=["default"], +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +# Do something interesting with the token... +auth_token = auth_response.context.token +``` + + + + + + +```javascript {20-21} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start(userId, "asana", { + scopes: ["default"], +}); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +const response = await client.auth.waitForCompletion(authResponse); + +// Do something interesting with the token... +const auth_token = response.context.token; +``` + + + + +You can use the auth token to call the [Get multiple tasks endpoint](https://developers.asana.com/reference/gettasks) and read information about tasks, for example. Any Asana API endpoint can be called with the auth token. + +## Using Asana auth in custom tools + +You can use the pre-built [Arcade Asana MCP Server](/mcp-servers/productivity/asana) to quickly build agents and AI apps that interact with Asana. + +If the pre-built tools in the Asana MCP Server don't meet your needs, you can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with Asana API. + +Use the `Asana()` auth class to specify that a tool requires authorization with Asana. The authentication token needed to call the Asana API is available in the tool context through the `context.get_auth_token_or_empty()` method. + + + As explained [above](#create-an-asana-app), the Asana granular permission + scopes are in preview and not yet supported. The `"default"` scope should be + used as the only scope in all tools. + + +```python {9,17} +from typing import Annotated + +import httpx + +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import Asana + + +@tool(requires_auth=Asana(scopes=["default"])) +async def delete_task( + context: ToolContext, + task_id: Annotated[str, "The ID of the task to delete."], +) -> Annotated[dict, "Details of the deletion response"]: + """Deletes a task.""" + url = f"https://api.asana.com/api/1.0/tasks/{task_id}" + headers = { + "Authorization": f"Bearer {context.get_auth_token_or_empty()}", + "Accept": "application/json", + } + + async with httpx.AsyncClient() as client: + response = await client.delete(url, headers=headers) + response.raise_for_status() + return response.json() +``` + + +Your new tool can be called like demonstrated below: + + + + + If you are self-hosting, change the `base_url` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`. + + +```python +from arcadepy import Arcade + +client = Arcade(base_url="https://api.arcade.dev") # Automatically finds the `ARCADE_API_KEY` env variable + +USER_ID = "{arcade_user_id}" +TOOL_NAME = "Asana.DeleteTask" + +auth_response = client.tools.authorize(tool_name=TOOL_NAME, user_id=USER_ID) + +if auth_response.status != "completed": + print(f"Click this link to authorize: {auth_response.url}") + +# Wait for the authorization to complete +client.auth.wait_for_completion(auth_response) + +tool_input = { + "task_id": "1234567890", +} + +response = client.tools.execute( + tool_name=TOOL_NAME, + input=tool_input, + user_id=USER_ID, +) +print(response.output.value) +``` + + + + + If you are self-hosting, change the `baseURL` parameter in the `Arcade` constructor to match your Arcade Engine URL. By default, the Engine will be available at `http://localhost:9099`. + + +```javascript +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade({ baseURL: "https://api.arcade.dev" }); // Automatically finds the `ARCADE_API_KEY` env variable + +const USER_ID = "{arcade_user_id}"; +const TOOL_NAME = "Asana.DeleteTask"; + +// Start the authorization process +const authResponse = await client.tools.authorize({ + tool_name: TOOL_NAME, + user_id: USER_ID, +}); + +if (authResponse.status !== "completed") { + console.log(`Click this link to authorize: ${authResponse.url}`); +} + +// Wait for the authorization to complete +await client.auth.waitForCompletion(authResponse); + +const toolInput = { + task_id: "1234567890", +}; + +const response = await client.tools.execute({ + tool_name: TOOL_NAME, + input: toolInput, + user_id: USER_ID, +}); + +console.log(response.output.value); +``` + + + diff --git a/app/en/home/sharing-with-end-users/custom-auth/atlassian/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/atlassian/page.mdx new file mode 100644 index 000000000..ec4bc6519 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/atlassian/page.mdx @@ -0,0 +1,182 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Atlassian + + + At this time, Arcade does not offer a default Atlassian Auth Provider. To use + Atlassian auth, you must create a custom Auth Provider with your own Atlassian + OAuth 2.0 credentials as described below. + + +The Atlassian auth provider enables tools and agents to call the Atlassian API on behalf of a user. + +### What's documented here + +This page describes how to use and configure Atlassian auth with Arcade. + +This auth provider is used by: + +- Your [app code](#using-atlassian-auth-in-app-code) that needs to call Atlassian APIs +- Or, your [custom tools](#using-atlassian-auth-in-custom-tools) that need to call Atlassian APIs + +## Configuring Atlassian auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Atlassian app credentials. This way, your users will see your application's name requesting permission. + + +Before showing how to configure your Atlassian app credentials, let's go through the steps to create an Atlassian app. + +### Create an Atlassian app + +- Create a Atlassian app in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) +- In the Authorization tab, click the "Add" action button and set the Callback URL to the redirect URL generated by Arcade (see below) +- In the Permissions tab, enable any permissions you need for your app +- In the Settings tab, copy the Client ID and Secret to use below + +## Configuring your own Atlassian Auth Provider in Arcade + + + + + +### Configure Atlassian Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **Atlassian**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-atlassian-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Atlassian app. +- Note the **Redirect URL** generated by Arcade. This must be added to your Atlassian app as a Callback URL. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + +When you use tools that require Atlassian auth using your Arcade account credentials, Arcade will automatically use this Atlassian OAuth provider. If you have multiple Atlassian providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + +## Using Atlassian auth in app code + +Use the Atlassian auth provider in your own agents and AI apps to get a user token for the Atlassian API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Atlassian API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="atlassian", + scopes=["read:me", "read:jira-user", "read:confluence-user"], +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-10} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable + +const userId = "{arcade_user_id}"; + +// Start the authorization process +let authResponse = await client.auth.start(userId, "atlassian", { + scopes: ["read:me", "read:jira-user", "read:confluence-user"], +}); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Atlassian auth in custom tools + +You can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Atlassian API. + +Use the `Atlassian()` auth class to specify that a tool requires authorization with Atlassian. The `context.authorization.token` field will be automatically populated with the user's Atlassian token: + +```python {5-6,9-13,23} +from typing import Annotated, Optional + +import httpx + +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import Atlassian + + +@tool( + requires_auth=Atlassian( + scopes=["read:jira-work"], + ) +) +async def list_projects( + context: ToolContext, + query: Annotated[ + Optional[str], + "The query to filter the projects by. Defaults to empty string to list all projects.", + ] = "", +) -> Annotated[dict, "The list of projects in a user's Jira instance"]: + """List a Jira user's projects.""" + url = f"https://api.atlassian.com/ex/jira//rest/api/3/project/search?query={query}" + headers = {"Authorization": f"Bearer {context.authorization.token}"} + + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers) + response.raise_for_status() + return response.json() +``` diff --git a/app/en/home/sharing-with-end-users/custom-auth/calendly/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/calendly/page.mdx new file mode 100644 index 000000000..a2693d9ab --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/calendly/page.mdx @@ -0,0 +1,272 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Calendly + +The Calendly auth provider enables tools and agents to call [Calendly APIs](https://developer.calendly.com/api-docs) on behalf of a user using OAuth 2.0 authentication. + + + Want to quickly get started with Calendly in your agent or AI app? The + pre-built [Arcade Calendly MCP Server](/mcp-servers/productivity/calendly-api) + is what you want! + + +### What's documented here + +This page describes how to use and configure Calendly auth with Arcade. + +This auth provider is used by: + +- The [Arcade Calendly MCP Server](/mcp-servers/productivity/calendly-api), which provides pre-built tools for interacting with Calendly +- Your [app code](#using-calendly-auth-in-app-code) that needs to call the Calendly API +- Or, your [custom tools](#using-calendly-auth-in-custom-tools) that need to call the Calendly API + +## Configuring Calendly auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Calendly app credentials. This way, your users will see your application's name requesting permission. + +Before showing how to configure your Calendly app credentials, let's go through the steps to create a Calendly app. + +### Create a Calendly app + +To integrate with Calendly's API, you'll need to create a developer account and register an OAuth application: + + + +#### Create a Calendly developer account + +1. Navigate to [developer.calendly.com/create-a-developer-account](https://developer.calendly.com/create-a-developer-account) +2. Sign up using your GitHub or Google account +3. Complete the registration process + +#### Register a new OAuth application + +1. Click on **Create New App** or **Register an App** +2. Fill in the required details: + - **Application Name**: Choose a descriptive name for your application + - **Type**: Select **Web** or **Native** based on your application type + - **Environment**: Choose **Sandbox** (for testing) or **Production** + - **Redirect URI**: Add the redirect URL generated by Arcade (see configuration section below) + - For Sandbox: HTTP with localhost is allowed (e.g., `http://localhost:1234`) + - For Production: HTTPS is required + +#### Save your credentials + +1. After registration, you'll receive your **Client ID**, **Client Secret**, and **Webhook Signing Key** +2. **Important**: Copy and save these credentials immediately, as the Client Secret and Webhook Signing Key won't be accessible again + + + +For detailed instructions, refer to Calendly's [Getting Started guide](https://developer.calendly.com/getting-started) and [OAuth documentation](https://developer.calendly.com/api-docs/0b07b0a0b0b07-get-authorization-code). + +Next, add the Calendly app to Arcade. + +## Configuring your own Calendly Auth Provider in Arcade + + + + +### Configure Calendly Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **OAuth 2.0** tab at the top. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "arcade-calendly"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Calendly app. +- Configure the OAuth 2.0 endpoints: + - **Authorization URL**: `https://auth.calendly.com/oauth/authorize` + - **Token URL**: `https://auth.calendly.com/oauth/token` +- Note the **Redirect URL** generated by Arcade. This must be set as your Calendly app's Redirect URI. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + + + + + +### Configure Calendly Auth Using Configuration File + + + This method is only available when you are [self-hosting the + engine](/home/deployment/on-prem-mcp) + + + + +#### Set environment variables + +Set the following environment variables: + +```bash +export CALENDLY_CLIENT_ID="" +export CALENDLY_CLIENT_SECRET="" +``` + +Or, you can set these values in a `.env` file: + +```bash +CALENDLY_CLIENT_ID="" +CALENDLY_CLIENT_SECRET="" +``` + +#### Edit the Engine configuration + +Edit the `engine.yaml` file and add a new item to the `auth.providers` section: + +```yaml +auth: + providers: + - id: arcade-calendly + description: Calendly OAuth 2.0 provider + enabled: true + type: oauth2 + client_id: ${env:CALENDLY_CLIENT_ID} + client_secret: ${env:CALENDLY_CLIENT_SECRET} + oauth2: + authorize_request: + endpoint: "https://auth.calendly.com/oauth/authorize" + params: + response_type: code + client_id: "{{client_id}}" + redirect_uri: "{{redirect_uri}}" + state: "{{state}}" + token_request: + endpoint: "https://auth.calendly.com/oauth/token" + params: + grant_type: authorization_code + client_id: "{{client_id}}" + client_secret: "{{client_secret}}" + redirect_uri: "{{redirect_uri}}" + response_content_type: application/json +``` + + + + + + +When you use tools that require Calendly auth using your Arcade account credentials, Arcade will automatically use this Calendly OAuth provider. If you have multiple Calendly providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + +## Using Calendly auth in app code + +Use the Calendly auth provider in your own agents and AI apps to get a user token for the Calendly API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Calendly API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="arcade-calendly" +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-11} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start(userId, "arcade-calendly"); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Calendly auth in custom tools + +You can use the pre-built [Arcade Calendly MCP Server](/mcp-servers/productivity/calendly-api) to quickly build agents and AI apps that interact with Calendly. + +If the pre-built tools in the Calendly MCP Server don't meet your needs, you can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Calendly API. + +Use the `OAuth2()` auth class to specify that a tool requires authorization with Calendly. The `context.authorization.token` field will be automatically populated with the user's Calendly token: + +```python {8-12,22} +from typing import Annotated + +import httpx +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import OAuth2 + + +@tool( + requires_auth=OAuth2(provider_id="arcade-calendly") +) +async def get_user_info( + context: ToolContext, +) -> Annotated[dict, "The user information."]: + """ + Retrieve the authenticated user's information from Calendly. + """ + url = "https://api.calendly.com/users/me" + headers = { + "Authorization": context.authorization.token, + } + + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers) + response.raise_for_status() + return dict(response.json()) +``` + +For more details about Calendly's authentication, refer to the [Calendly Authentication documentation](https://developer.calendly.com/how-to-guides/authentication). diff --git a/app/en/home/sharing-with-end-users/custom-auth/clickup/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/clickup/page.mdx new file mode 100644 index 000000000..5a5139587 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/clickup/page.mdx @@ -0,0 +1,171 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# ClickUp + +The ClickUp auth provider enables tools and agents to call the ClickUp API on behalf of a user. + +### What's documented here + +This page describes how to use and configure ClickUp auth with Arcade. + +This auth provider is used by: + +- Your [app code](#using-clickup-auth-in-app-code) that needs to call ClickUp APIs +- Or, your [custom tools](#using-clickup-auth-in-custom-tools) that need to call ClickUp APIs + +## Configuring ClickUp auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + +In a production environment, you will most likely want to use your own ClickUp app +credentials. This way, your users will see your application's name requesting permission. + + +Before showing how to configure your ClickUp app credentials, let's go through the steps to create a ClickUp app. + +### Create a ClickUp app + +- Navigate to your ClickUp workspace and go to **Settings → Apps** +- Click **Create new app** in the OAuth Apps section +- Fill in your app name and description +- Set the OAuth Redirect URL to: `https://cloud.arcade.dev/api/v1/oauth/callback` +- Copy the Client ID and Client Secret, which you'll need below + +## Configuring your own ClickUp Auth Provider in Arcade + + + + +### Configure ClickUp Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at `http://localhost:9099/dashboard`. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **ClickUp**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-clickup-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your ClickUp app. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + +When you use tools that require ClickUp auth using your Arcade account credentials, Arcade will automatically use this ClickUp OAuth provider. If you have multiple ClickUp providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + + +## Using ClickUp auth in app code + +Use the ClickUp auth provider in your own agents and AI apps to get a user-scoped token for the ClickUp API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the ClickUp API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="clickup", +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# TODO: Do something interesting with the token... +``` + + + + +```javascript {8-10} +import { Arcade } from "arcade-js"; + +const client = new Arcade(); + +const auth = await client.auth.start({ + provider: "clickup", +}); + +if (auth.status !== "completed") { + console.log("Finish authorization at:", auth.url); + await client.auth.waitForCompletion(auth); +} + +const { token } = auth.context; +// Use the token in ClickUp API requests +``` + + + + +## Using ClickUp auth in custom tools + +You can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the ClickUp API. + +Use the `ClickUp()` auth class to specify that a tool requires authorization with ClickUp. The `context.authorization.token` field will be automatically populated with the user's ClickUp token: + +```python {5-6,9-13,20} +import httpx +from arcade_tdk import tool, ToolContext +from arcade_tdk.auth import ClickUp + +@tool(requires_auth=ClickUp()) +async def get_my_workspaces(context: ToolContext) -> dict: + """Get the authenticated user's workspaces (teams) from ClickUp.""" + token = context.authorization.token + + # Make authenticated request to ClickUp API + async with httpx.AsyncClient() as client: + response = await client.get( + "https://api.clickup.com/api/v2/team", + headers={ + "Authorization": token, + "Content-Type": "application/json" + } + ) + + if response.status_code == 200: + data = response.json() + teams = data.get("teams", []) + return { + "success": True, + "teams": [{"id": team["id"], "name": team["name"]} for team in teams] + } + else: + return { + "success": False, + "error": f"ClickUp API error: {response.status_code} - {response.text}" + } +``` diff --git a/app/en/home/sharing-with-end-users/custom-auth/discord/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/discord/page.mdx new file mode 100644 index 000000000..c291cf398 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/discord/page.mdx @@ -0,0 +1,183 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Discord + + + At this time, Arcade does not offer a default Discord Auth Provider. To use + Discord auth, you must create a custom Auth Provider with your own Discord + OAuth 2.0 credentials as described below. + + +The Discord auth provider enables tools and agents to call the Discord API on behalf of a user. + +### What's documented here + +This page describes how to use and configure Discord auth with Arcade. + +This auth provider is used by: + +- Your [app code](#using-discord-auth-in-app-code) that needs to call Discord APIs +- Or, your [custom tools](#using-discord-auth-in-custom-tools) that need to call Discord APIs + +## Configuring Discord auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Discord app credentials. This way, your users will see your application's name requesting permission. + + +Before showing how to configure your Discord app credentials, let's go through the steps to create a Discord app. + +### Create a Discord app + +- Create a Discord Application in the [Discord developer portal](https://discord.com/developers/applications) +- In the OAuth2 tab, set the redirect URI to the redirect URL generated by Arcade (see below) +- Copy the Client ID and Client Secret (you may need to reset the secret to see it) + +## Configuring your own Discord Auth Provider in Arcade + + + + + +### Configure Discord Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **Discord**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-discord-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Discord app. +- Note the **Redirect URL** generated by Arcade. This must be added to your Discord app's Redirect URIs. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + +When you use tools that require Discord auth using your Arcade account credentials, Arcade will automatically use this Discord OAuth provider. If you have multiple Discord providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + + +## Using Discord auth in app code + +Use the Discord auth provider in your own agents and AI apps to get a user token for the Discord API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Discord API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="discord", + scopes=["identify", "email", "guilds", "guilds.join"], +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-10} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start(userId, "discord", { + scopes: ["identify", "email", "guilds", "guilds.join"], +}); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Discord auth in custom tools + +You can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Discord API. + +Use the `Discord()` auth class to specify that a tool requires authorization with Discord. The `context.authorization.token` field will be automatically populated with the user's Discord token: + +```python {5-6,9-13,23} +from typing import Annotated, Optional + +import httpx + +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import Discord + + +@tool( + requires_auth=Discord( + scopes=["guilds"], + ) +) +async def list_servers( + context: ToolContext, + user_id: Annotated[ + Optional[str], + "The user's user ID. Defaults to '@me' for the current user.", + ] = "@me", +) -> Annotated[dict, "List of servers the user is a member of"]: + """List a Discord user's servers they are a member of.""" + url = f"https://discord.com/api/users/{user_id}/guilds" + headers = {"Authorization": f"Bearer {context.authorization.token}"} + + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers) + response.raise_for_status() + return response.json() +``` diff --git a/app/en/home/sharing-with-end-users/custom-auth/figma/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/figma/page.mdx new file mode 100644 index 000000000..643f92a21 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/figma/page.mdx @@ -0,0 +1,294 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Figma + +The Figma auth provider enables tools and agents to call [Figma APIs](https://www.figma.com/developers/api) on behalf of a user using OAuth 2.0 authentication. + + + Want to quickly get started with Figma in your agent or AI app? The pre-built + [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api) is what you + want! + + +### What's documented here + +This page describes how to use and configure Figma auth with Arcade. + +This auth provider is used by: + +- The [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api), which provides pre-built tools for interacting with Figma +- Your [app code](#using-figma-auth-in-app-code) that needs to call the Figma API +- Or, your [custom tools](#using-figma-auth-in-custom-tools) that need to call the Figma API + +## Configuring Figma auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Figma app credentials. This way, your users will see your application's name requesting permission. + +Before showing how to configure your Figma app credentials, let's go through the steps to create a Figma app. + +### Create a Figma app + +To integrate with Figma's API, you'll need to set up OAuth 2.0 authentication by creating an app in the Figma Developer Portal: + + + +#### Access the Figma Developer Portal + +Navigate to the [Figma Developer Portal](https://www.figma.com/developers/) and sign in with your existing Figma credentials or create a new account. + +#### Create a new app + +1. Once logged in, go to your developer dashboard and select "My Apps" +2. Click on "Create a new app" +3. Fill in the required details: + - **App Name**: Choose a descriptive name for your application + - **Website**: Provide the URL of your application's website + - **App Logo**: Upload a 100x100px PNG image representing your app + +#### Set up OAuth configuration + +1. After creating your app, you'll receive a `client_id` and `client_secret` +2. Set the redirect URI to the redirect URL generated by Arcade (see configuration section below) +3. Configure the required scopes for your application: + - `files:read` - Read access to files + - `file_comments:write` - Write access to file comments + - Add other scopes as needed for your use case + + + +For detailed instructions, refer to Figma's official [Authentication documentation](https://developers.figma.com/docs/rest-api/authentication/). + +Next, add the Figma app to Arcade. + +## Configuring your own Figma Auth Provider in Arcade + + + + +### Configure Figma Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **OAuth 2.0** tab at the top. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "arcade-figma"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Figma app. +- Configure the OAuth 2.0 endpoints: + - **Authorization URL**: `https://www.figma.com/oauth` + - **Token URL**: `https://www.figma.com/api/oauth/token` +- Note the **Redirect URL** generated by Arcade. This must be set as your Figma app's redirect URI. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + + + + + +### Configure Figma Auth Using Configuration File + + + This method is only available when you are [self-hosting the + engine](/home/deployment/on-prem-mcp) + + + + +#### Set environment variables + +Set the following environment variables: + +```bash +export FIGMA_CLIENT_ID="" +export FIGMA_CLIENT_SECRET="" +``` + +Or, you can set these values in a `.env` file: + +```bash +FIGMA_CLIENT_ID="" +FIGMA_CLIENT_SECRET="" +``` + +#### Edit the Engine configuration + +Edit the `engine.yaml` file and add a new item to the `auth.providers` section: + +```yaml +auth: + providers: + - id: arcade-figma + description: Figma OAuth 2.0 provider + enabled: true + type: oauth2 + client_id: ${env:FIGMA_CLIENT_ID} + client_secret: ${env:FIGMA_CLIENT_SECRET} + oauth2: + scope_delimiter: "," + authorize_request: + endpoint: "https://www.figma.com/oauth" + params: + response_type: code + client_id: "{{client_id}}" + redirect_uri: "{{redirect_uri}}" + scope: "{{scopes}}" + state: "{{state}}" + token_request: + endpoint: "https://www.figma.com/api/oauth/token" + auth_method: client_secret_basic + params: + grant_type: authorization_code + client_id: "{{client_id}}" + client_secret: "{{client_secret}}" + redirect_uri: "{{redirect_uri}}" + response_content_type: application/json +``` + + + + + + +When you use tools that require Figma auth using your Arcade account credentials, Arcade will automatically use this Figma OAuth provider. If you have multiple Figma providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + +## Using Figma auth in app code + +Use the Figma auth provider in your own agents and AI apps to get a user token for the Figma API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Figma API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="arcade-figma", + scopes=["files:read", "file_comments:write"] +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-11} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start(userId, "arcade-figma", [ + "files:read", + "file_comments:write", +]); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Figma auth in custom tools + +You can use the pre-built [Arcade Figma MCP Server](/mcp-servers/productivity/figma-api) to quickly build agents and AI apps that interact with Figma. + +If the pre-built tools in the Figma MCP Server don't meet your needs, you can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Figma API. + +Use the `OAuth2()` auth class to specify that a tool requires authorization with Figma. The `context.authorization.token` field will be automatically populated with the user's Figma token: + +```python {8-12,22} +from typing import Annotated + +import httpx +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import OAuth2 + + +@tool( + requires_auth=OAuth2( + provider_id="arcade-figma", + scopes=["files:read"] + ) +) +async def get_figma_file( + context: ToolContext, + file_key: Annotated[str, "The Figma file key to retrieve."], +) -> Annotated[dict, "The Figma file data."]: + """ + Retrieve a Figma file by its key. + """ + url = f"https://api.figma.com/v1/files/{file_key}" + headers = { + "Authorization": context.authorization.token, + } + + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers) + response.raise_for_status() + return dict(response.json()) +``` + +## Available Scopes + +Figma supports various OAuth scopes that determine the level of access your application has: + +- `files:read` - Read access to files +- `file_comments:write` - Write access to file comments +- `file_dev_resources:write` - Write access to dev resources +- `file_variables:read` - Read access to variables +- `file_variables:write` - Write access to variables +- `webhooks:write` - Write access to webhooks + +For a complete list of available scopes and their descriptions, refer to the [Figma API documentation](https://www.figma.com/developers/api#authentication). diff --git a/app/en/home/sharing-with-end-users/custom-auth/github/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/github/page.mdx new file mode 100644 index 000000000..eced918bb --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/github/page.mdx @@ -0,0 +1,1215 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# GitHub + +The GitHub auth provider enables tools and agents to call [GitHub APIs](https://docs.github.com/en/rest/overview/resources-in-the-rest-api) on behalf of a user. + + + Want to quickly get started with GitHub in your agent or AI app? The pre-built + [Arcade GitHub MCP Server](/mcp-servers/development/github) is what you want! + + +## What's documented here + +This page describes how to use and configure GitHub auth with Arcade. + +This auth provider is used by: + +- The [Arcade GitHub MCP Server](/mcp-servers/development/github), which provides pre-built tools for interacting with GitHub +- Your [app code](#using-github-auth-in-app-code) that needs to call the GitHub API +- Or, your [custom tools](#using-github-auth-in-custom-tools) that need to call the GitHub API + +--- + +## Why Arcade Uses GitHub Apps (Not OAuth Apps) + +### Arcade's Decision + +Arcade's security team selected **GitHub Apps** over OAuth Apps for the GitHub toolkit based on three critical factors: + +1. **🎯 GitHub's Recommendation**: OAuth Apps are soft-deprecated. GitHub actively recommends Apps for new integrations and invests in their development. + +2. **🔐 Fine-Grained Security**: GitHub Apps support granular permissions (e.g., "Read pull requests"), while OAuth Apps only offer coarse scopes (e.g., `repo` = full repository access). + +3. **🏢 Enterprise Control**: Admins can approve exact permissions and see all app installations. OAuth Apps bypass organizational oversight. + + + **Important**: When creating your GitHub integration with Arcade, you must use + a **GitHub App** (not an OAuth App). GitHub Apps provide the security and + permission model required for production use. + + +### Quick Comparison + +| Aspect | 🏆 GitHub Apps (Required) | OAuth Apps (Not Supported) | +| ---------------- | ------------------------------------ | ----------------------------------------- | +| **Permissions** | Fine-grained (e.g., "Read contents") | Broad scopes (e.g., `repo` = full access) | +| **Installation** | Per repository/org (admin approval) | Per user (no approval) | +| **Access** | Only installed repositories | All user repositories | +| **Tokens** | Scoped, short-lived | Broad, long-lived | +| **Identity** | Acts as app | Acts as user | +| **Security** | ⭐⭐⭐⭐⭐ Highest | ⭐⭐⭐ Good | +| **Best For** | Production, CI/CD, Enterprise | Personal, Prototypes | + + +**GitHub Enterprise Server (GHES) Limitation** + +GitHub Apps created on github.com **cannot** be installed on GitHub Enterprise Server instances, and vice versa. Each GHES instance requires its own separate GitHub App registration. + +- ✅ Apps on github.com work for all github.com users +- ❌ Apps on github.com **DO NOT** work for GHES instances +- ✅ Each GHES instance must register its own GitHub App +- ✅ You can use the same manifest/configuration for multiple instances + +[Learn more about GHES GitHub Apps](https://docs.github.com/en/apps/sharing-github-apps/making-your-github-app-available-for-github-enterprise-server) + + + +### Why Enterprises Choose GitHub Apps + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
🔐 Permission Model +Least-privilege access. Grant only exact permissions needed (e.g., "Read contents" vs full repo access). Minimizes blast radius and supports compliance (SOC 2, ISO 27001). +
+ 🏢 Installation + + Centralized control. IT/security teams see all app + installations, enforce policies, prevent shadow IT. Admin approval ensures + integrations are vetted and documented. +
+ 🎯 Access Scope + + Reduced attack surface. Apps only access explicitly + installed repositories. Critical for organizations with repositories at + different sensitivity levels. +
+ 🔑 Token Type + + Better security posture. Tokens are scoped and revocable + instantly. Long-lived OAuth tokens remain valid for months if compromised. +
+ 👤 Identity + + Clear accountability. Actions attributed to app, not users. + Essential for compliance audits and security investigations. +
📊 Audit Trail +Clear audit logs. Easy to identify automated vs human actions. Essential for SOC 2, HIPAA compliance. +
+ +--- + +## Creating a GitHub App + +
+ +
+ +## Why Evaluate Tool Calling by Task? + +Language models augmented with tool-use capabilities can perform complex tasks by invoking external tools or APIs. However, without proper evaluation, these models might: + +- **Misinterpret user intents**, leading to incorrect tool selection. +- **Provide incorrect arguments** to tools, causing failures or undesired outcomes. +- **Fail to execute the necessary sequence of tool calls**, especially in tasks requiring multiple steps. + +Evaluating tool calling by task ensures that the language model can handle specific scenarios reliably, providing confidence in its performance in production settings. + +## Evaluation Scoring + +Scoring in the evaluation framework is based on comparing the model's actual tool calls with the expected ones for each evaluation case. The total score for a case depends on: + +1. **Tool Selection**: Whether the model selected the correct tools for the task. +2. **Tool Call Arguments**: The correctness of the arguments provided to the tools, evaluated by critics. +3. **Evaluation Rubric**: Each aspect of the evaluation is weighted according to the rubric, affecting its impact on the final score. + +The evaluation result includes: + +- **Score**: A normalized value between 0.0 and 1.0. +- **Result**: + - _Passed_: Score is above the fail threshold. + - _Failed_: Score is below the fail threshold. + - _Warned_: Score is between the warning and fail thresholds. + +## Critics: Types and Usage + +Critics are essential for evaluating the correctness of tool call arguments. Different types of critics serve various evaluation needs: + +### BinaryCritic + +`BinaryCritic`s check for exact matches between expected and actual values after casting. + +- **Use Case**: When exact values are required (e.g., specific numeric parameters). +- **Example**: Ensuring the model provides the exact user ID in a function call. + +### NumericCritic + +`NumericCritic` evaluates numeric values within a specified range, allowing for acceptable deviations. + +- **Use Case**: When values can be approximate but should be within a certain threshold. +- **Example**: Accepting approximate results in mathematical computations due to floating-point precision. + +### SimilarityCritic + +`SimilarityCritic` measures the similarity between expected and actual string values using metrics like cosine similarity. + +- **Use Case**: When the exact wording isn't critical, but the content should be similar. +- **Example**: Evaluating if the message content in a communication tool is similar to the expected message. + +### DatetimeCritic + +`DatetimeCritic` evaluates the closeness of datetime values within a specified tolerance. + +- **Use Case**: When datetime values should be within a certain range of the expected time. +- **Example**: Verifying if a scheduled event time is close enough to the intended time. + +### Choosing the Right Critic + +- **Exact Matches Needed**: Use **BinaryCritic** for strict equality. +- **Numeric Ranges**: Use **NumericCritic** when a tolerance is acceptable. +- **Textual Similarity**: Use **SimilarityCritic** for comparing messages or descriptions. +- **Datetime Tolerance**: Use **DatetimeCritic** when a tolerance is acceptable for datetime comparisons. + +Critics are defined with fields such as `critic_field`, `weight`, and parameters specific to their types (e.g., `similarity_threshold` for `SimilarityCritic`). + +## Rubrics and Setting Thresholds + +An **EvalRubric** defines the evaluation criteria and thresholds for determining pass/fail outcomes. Key components include: + +- **Fail Threshold**: The minimum score required to pass the evaluation. +- **Warn Threshold**: The score threshold for issuing a warning. +- **Weights**: Assigns importance to different aspects of the evaluation (e.g., tool selection, argument correctness). + +### Setting Up a Rubric + +- **Define Fail and Warn Thresholds**: Choose values between 0.0 and 1.0 to represent acceptable performance levels. +- **Assign Weights**: Allocate weights to tool selection and critics to reflect their importance in the overall evaluation. +- **Configure Failure Conditions**: Set flags like `fail_on_tool_selection` to enforce strict criteria. + +### Example Rubric Configuration: + +A rubric that requires a score of at least 0.85 to pass and issues a warning if the score is between 0.85 and 0.95: + +- Fail Threshold: 0.85 +- Warn Threshold: 0.95 +- Fail on Tool Selection: True +- Tool Selection Weight: 1.0 + +```python +rubric = EvalRubric( + fail_threshold=0.85, + warn_threshold=0.95, + fail_on_tool_selection=True, + tool_selection_weight=1.0, +) +``` + +## Building an Evaluation Suite + +An **EvalSuite** orchestrates the running of multiple evaluation cases. Here's how to build one: + +1. **Initialize EvalSuite**: Provide a name, system message, tool catalog, and rubric. +2. **Add Evaluation Cases**: Use `add_case` or `extend_case` to include various scenarios. +3. **Specify Expected Tool Calls**: Define the tools and arguments expected for each case. +4. **Assign Critics**: Attach critics relevant to each case to evaluate specific arguments. +5. **Run the Suite**: Execute the suite using the Arcade CLI to collect results. + +### Example: Math Tools Evaluation Suite + +An evaluation suite for math tools might include cases such as: + +- **Adding Two Large Numbers**: + - **User Message**: "Add 12345 and 987654321" + - **Expected Tool Call**: `add(a=12345, b=987654321)` + - **Critics**: + - `BinaryCritic` for arguments `a` and `b` +- **Calculating Square Roots**: + - **User Message**: "What is the square root of 3224990521?" + - **Expected Tool Call**: `sqrt(a=3224990521)` + - **Critics**: + - `BinaryCritic` for argument `a` + +### Example: Slack Messaging Tools Evaluation Suite + +An evaluation suite for Slack messaging tools might include cases such as: + +- **Sending a Direct Message**: + - **User Message**: "Send a direct message to johndoe saying 'Hello, can we meet at 3 PM?'" + - **Expected Tool Call**: `send_dm_to_user(user_name='johndoe', message='Hello, can we meet at 3 PM?')` + - **Critics**: + - `BinaryCritic` for `user_name` + - `SimilarityCritic` for `message` +- **Posting a Message to a Channel**: + - **User Message**: "Post 'The new feature is now live!' in the #announcements channel" + - **Expected Tool Call**: `send_message_to_channel(channel_name='announcements', message='The new feature is now live!')` + - **Critics**: + - `BinaryCritic` for `channel_name` + - `SimilarityCritic` for `message` diff --git a/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx b/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx index 48d796c5a..b43b5bfdb 100644 --- a/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx +++ b/app/en/home/creating-tools/new-functionality/custom-toolkit/page.mdx @@ -1,7 +1,8 @@ -# custom-toolkit +--- +title: "Write custom toolkit" +description: "Learn how to write custom toolkits" +--- -Documentation coming soon. +# Write custom toolkit -## Overview - -This section will contain detailed information about custom-toolkit. +Coming soon! diff --git a/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx b/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx index 7acdc5dcb..8d37291fc 100644 --- a/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx +++ b/app/en/home/creating-tools/new-functionality/eval-new-functionality/page.mdx @@ -1,7 +1,8 @@ -# eval-new-functionality +--- +title: "Write eval for functionality you want" +description: "Learn how to write evaluations for functionality you want" +--- -Documentation coming soon. +# Write eval for functionality you want -## Overview - -This section will contain detailed information about eval-new-functionality. +Coming soon! diff --git a/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx b/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx index 8cfa6e27f..653e21c2f 100644 --- a/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx +++ b/app/en/home/creating-tools/newest-models/modify-tool-new-model/page.mdx @@ -1,7 +1,8 @@ -# modify-tool-new-model +--- +title: "Modify tool to work well with new model" +description: "Learn how to modify tools to work well with new models" +--- -Documentation coming soon. +# Modify tool to work well with new model -## Overview - -This section will contain detailed information about modify-tool-new-model. +Coming soon! diff --git a/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx b/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx index b29b2853e..3da62f894 100644 --- a/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx +++ b/app/en/home/creating-tools/newest-models/run-eval-new-model/page.mdx @@ -1,7 +1,8 @@ -# run-eval-new-model +--- +title: "Run existing eval and observe outcome with new model" +description: "Learn how to run existing evaluations with new models" +--- -Documentation coming soon. +# Run existing eval and observe outcome with new model -## Overview - -This section will contain detailed information about run-eval-new-model. +Coming soon! diff --git a/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx b/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx index 5ec9cca20..21b27b5ca 100644 --- a/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx +++ b/app/en/home/creating-tools/performance-tools/custom-tool-improvements/page.mdx @@ -1,7 +1,8 @@ -# custom-tool-improvements +--- +title: "Write custom tool that improves on relevant Starter tools" +description: "Learn how to write custom tools that improve on Starter tools" +--- -Documentation coming soon. +# Write custom tool that improves on relevant Starter tools -## Overview - -This section will contain detailed information about custom-tool-improvements. +Coming soon! diff --git a/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx b/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx index 4df143348..d5d282edd 100644 --- a/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx +++ b/app/en/home/creating-tools/performance-tools/eval-starter-tools/page.mdx @@ -1,7 +1,8 @@ -# eval-starter-tools +--- +title: "Write eval to assess combo of starter tools" +description: "Learn how to write evaluations for combinations of starter tools" +--- -Documentation coming soon. +# Write eval to assess combo of starter tools -## Overview - -This section will contain detailed information about eval-starter-tools. +Coming soon! diff --git a/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx b/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx index e3b7f1ae0..0920ed24c 100644 --- a/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx +++ b/app/en/home/creating-tools/performance-tools/run-evaluations-2/page.mdx @@ -1,7 +1,217 @@ -# run-evaluations-2 +--- +title: "Run evaluations" +description: "Learn how to run evaluations using Arcade" +--- -Documentation coming soon. +# Run evaluations with the Arcade CLI -## Overview +The Arcade Evaluation Framework allows you to run evaluations of your tool-enabled language models conveniently using the Arcade CLI. This enables you to execute your evaluation suites, gather results, and analyze the performance of your models in an efficient and streamlined manner. -This section will contain detailed information about run-evaluations-2. + + + +Run evaluations of your tool-enabled language models using the Arcade CLI. + + + + + +- [Arcade CLI](/home/arcade-cli) +- [An MCP Server](/home/build-tools/create-a-mcp-server) +- [Create an evaluation suite](/home/evaluate-tools/create-an-evaluation-suite) + + + + + +- How to use the `arcade evals` CLI command to run evaluations. + + + + +### Using the `arcade evals` Command + +To run evaluations, use the `arcade evals` command provided by the Arcade CLI. This command searches for evaluation files in the specified directory, executes any functions decorated with `@tool_eval`, and displays the results. + +#### Basic Usage + +```bash +arcade evals +``` + +- ``: The directory containing your evaluation files. By default, it searches the current directory (`.`). + +For example, to run evaluations in the current directory: + +```bash +arcade evals +``` + +#### Evaluation File Naming Convention + +The `arcade evals` command looks for Python files that start with `eval_` and end with `.py` (e.g., `eval_math_tools.py`, `eval_slack_messaging.py`). These files should contain your evaluation suites. + +#### Command Options + +The `arcade evals` command supports several options to customize the evaluation process: + +- `--details`, `-d`: Show detailed results for each evaluation case, including critic feedback. + + Example: + + ```bash + arcade evals --details . + ``` + +- `--models`, `-m`: Specify the models to use for evaluation. Provide a comma-separated list of model names. + + Example: + + ```bash + arcade evals --models gpt-4o,gpt-5 . + ``` + +- `--max-concurrent`, `-c`: Set the maximum number of concurrent evaluations to run in parallel. + + Example: + + ```bash + arcade evals --max-concurrent 4 . + ``` + +- `--provider`, `-p`: The provider of the models to use for evaluation. Uses OpenAI by default. + + Example: + + ```bash + arcade evals --provider openai . + ``` + +- `--provider-api-key`, `-k`: The model provider API key. If not provided, will look for the appropriate environment variable based on the provider (e.g., OPENAI_API_KEY for openai provider), first in the current environment, then in the current working directory's .env file. + + Example: + + ```bash + arcade evals --provider-api-key my-api-key . + ``` + +- `--debug`: Show debug information in the CLI. + + Example: + + ```bash + arcade evals --debug . + ``` + +- `--help`: Show help information and exit. + + Example: + + ```bash + arcade evals --help + ``` + +#### Example Command + +Running evaluations in the `arcade_my_tools/evals` directory, showing detailed results, using the `gpt-5` model: + +```bash +arcade evals arcade_my_tools/evals --details --models gpt-5 -k my-openai-api-key +``` + +### Execution Process + +When you run the `arcade evals` command, the following steps occur: + +1. **Preparation**: The CLI loads the evaluation suites from the specified directory, looking for files that match the naming convention. + +2. **Execution**: The evaluation suites are executed asynchronously. Each suite's evaluation function, decorated with `@tool_eval`, is called with the appropriate configuration, including the model and concurrency settings. + +3. **Concurrency**: Evaluations can run concurrently based on the `--max-concurrent` setting, improving efficiency. + +4. **Result Aggregation**: Results from all evaluation cases and models are collected and aggregated. + +### Displaying Results + +After the evaluations are complete, the results are displayed in a concise and informative format, similar to testing frameworks like `pytest`. The output includes: + +- **Summary**: Shows the total number of cases, how many passed, failed, or issued warnings. + + Example: + + ``` + Summary -- Total: 5 -- Passed: 4 -- Failed: 1 + ``` + +- **Detailed Case Results**: For each evaluation case, the status (PASSED, FAILED, WARNED), the case name, and the score are displayed. + + Example: + + ``` + PASSED Add two large numbers -- Score: 1.00 + FAILED Send DM with ambiguous username -- Score: 0.75 + ``` + +- **Critic Feedback**: If the `--details` flag is used, detailed feedback from each critic is provided, highlighting matches, mismatches, and scores for each evaluated field. + + Example: + + ``` + Details: + user_name: + Match: False, Score: 0.00/0.50 + Expected: johndoe + Actual: john_doe + message: + Match: True, Score: 0.50/0.50 + ``` + +### Interpreting the Results + +- **Passed**: The evaluation case met or exceeded the fail threshold specified in the rubric. + +- **Failed**: The evaluation case did not meet the fail threshold. + +- **Warnings**: If the score is between the warn threshold and the fail threshold, a warning is issued. + +Use the detailed feedback to understand where the model's performance can be improved, particularly focusing on mismatches identified by critics. + +### Customizing Evaluations + +You can customize the evaluation process by adjusting: + +- **Rubrics**: Modify fail and warn thresholds, and adjust weights to emphasize different aspects of evaluation. + +- **Critics**: Add or modify critics in your evaluation cases to target specific arguments or behaviors. + +- **Concurrency**: Adjust the `--max-concurrent` option to optimize performance based on your environment. + +### Handling Multiple Models + +You can evaluate multiple models in a single run by specifying them in the `--models` option as a comma-separated list. This allows you to compare the performance of different models across the same evaluation suites. + +Example: + +```bash +arcade evals . --models gpt-4o,gpt-5 +``` + +### Considerations + +- **Evaluation Files**: Ensure your evaluation files are correctly named and contain the evaluation suites decorated with `@tool_eval`. + +- **Provider API Keys**: If you are using a different provider, you will need to set the appropriate API key in an environment variable, or use the `--provider-api-key` option. + +- **Tool Catalog**: Ensure your tool catalog is correctly defined and includes all the tools you want to evaluate. + +- **Weight distribution**: Ensure your weight distribution reflects the importance of each critic and that the sum of the weights is `1.0`. + +## Conclusion + +Running evaluations using the Arcade CLI provides a powerful and convenient way to assess the tool-calling capabilities of your language models. By leveraging the `arcade evals` command, you can efficiently execute your evaluation suites, analyze results, and iterate on your models and tools. + +Integrating this evaluation process into your development workflow helps ensure that your models interact with tools as expected, enhances reliability, and builds confidence in deploying actionable language models in production environments. + +## Next steps + +- **See an example MCP server with evaluations**: [Source code of a server with evaluations](https://github.com/ArcadeAI/arcade-mcp/tree/139cc2e54db0e5815f1c79dbe9e3285b4fe2bd66/examples/mcp_servers/server_with_evaluations) diff --git a/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx b/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx index f444c3598..71eab7fe1 100644 --- a/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx +++ b/app/en/home/creating-tools/performance-tools/types-of-tools/page.mdx @@ -1,7 +1,63 @@ -# types-of-tools +--- +title: "Types of Tools" +description: "Learn about Optimized and Starter tools" +--- -Documentation coming soon. +# Types of Tools -## Overview +Arcade offers two types of tools: -This section will contain detailed information about types-of-tools. +- Starter tools +- Optimized tools + +The distinction is merely a matter of how they are designed. Both types of tools can be used seamlessly in the same way. There is no difference 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). + +Before we understand the two types, let's first understand the background for why we need to differentiate between them. + +## 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. + +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. + +For instance, consider the following user prompt: + +> "Send a DM to John asking about a project update" + +The data model mismatches are: + +| Dimension | Chat interface | Slack HTTP API | +| --------- | -------------------------------------- | --------------------------------------- | +| Action | Send message to a person | Send message to a channel | +| Argument | `username = "John"` | `channel_id = ???` | + +In order to bridge the gap in the data models, the LLM has to make multiple API calls: + +1. Retrieve the current user's Slack ID +2. Browse the list of users to find John's ID +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. + +## 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. + +Following the example above, our Slack MCP Server offers the [`Slack.SendMessage`](/mcp-servers/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. We understand that your Agent or chatbot project might need capabilities not yet covered by our Optimized MCP Servers. For this reason, we also offer low-level Starter MCP Servers. + +## Starter tools + +To provide your Agent or chatbot with more freedom to interact with the upstream services, we offer Starter MCP Servers. + +Starter tools are heavily influenced by 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, Starter 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 Starter tool with your Agents or chatbots before using it in production. + +When your Agent's needs are covered by an Optimized tool, we recommend using it instead of a Starter one. Use Starter tools as a complement. Carefully engineer your prompts to ensure your Agent can call them safely. diff --git a/app/en/home/creating-tools/registry-early-access/page.mdx b/app/en/home/creating-tools/registry-early-access/page.mdx index cd83c0b3c..10cbd2fbd 100644 --- a/app/en/home/creating-tools/registry-early-access/page.mdx +++ b/app/en/home/creating-tools/registry-early-access/page.mdx @@ -1,3 +1,25 @@ -# Registry Early Access +--- +title: "Arcade Registry Early Access" +description: "Learn about the Arcade Registry and how to get early access" +--- -Get early access to the Arcade tool registry. \ No newline at end of file +import { EarlyAccessRegistrySurvey } from "@/app/_components/early-access-registry-survey"; +import { Callout } from "nextra/components"; +import { TakeSurvey } from "./take-survey"; + +# The Arcade Registry + +The **Arcade Registry** is how agentic tool developers share their work with the world. Arcade.dev is collecting all the integrations that agents will ever need in one place - think HuggingFace or Pypi but for LLM tools. A powerful community of open source and for-profit developers building out robust and evaluated workflows is how agents can be elevated to being _truly_ useful. + + + +**_The components of the Arcade Registry_** +![The Arcade Registry diagram](/images/registry/registry.png) + +Unlike traditional read-only tool libraries, Arcade.dev couples the runtime with the registry. This way we can collect real metrics and usage information about your tools, sharing meaningful information and feedback back to the developers. You'll get error reports and statistics about how your tools are getting used. Arcade.dev also makes it possible for developers to optionally choose to sell their tools with a markup on top of the Arcade platform fees. + +Thanks to the Arcade Engine, your MCP Servers will be available via all the protocols Arcade supports - be that MCP for locally-running applications, OXP for server applications, and whatever comes next. Use the open-source Arcade SDKs to future-proof your tools. + +We are seeking beta testers who are interested in building, maintaining, and sharing MCP Servers with the world in either a free-to-use or for-profit manner. Sign up today to join the Arcade Registry Beta. + + \ No newline at end of file diff --git a/app/en/home/creating-tools/registry-early-access/take-survey.tsx b/app/en/home/creating-tools/registry-early-access/take-survey.tsx new file mode 100644 index 000000000..89bf472d5 --- /dev/null +++ b/app/en/home/creating-tools/registry-early-access/take-survey.tsx @@ -0,0 +1,16 @@ +"use client"; + +import { Button } from "@arcadeai/design-system"; + +export const TakeSurvey = () => ( + +); diff --git a/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx b/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx index 0e691e68a..987c5a78b 100644 --- a/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx +++ b/app/en/home/creating-tools/tool-basics/build-mcp-server/page.mdx @@ -1,3 +1,274 @@ -# Build MCP Server to write custom tools +--- +title: "Build MCP Server QuickStart" +description: "Create your custom MCP Server with Arcade MCP" +--- -Learn how to build an MCP server to write custom tools. \ No newline at end of file +import { Steps, Tabs, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; +import { GuideOverview } from "@/app/_components/guide-overview"; + +# Build MCP Server QuickStart + + + + +Build and run an MCP Server with tools that you create. + + + + + +- Python 3.10 or higher +- The [`uv` package manager](https://docs.astral.sh/uv/getting-started/installation/) + + + + + +- Install `arcade-mcp`, the secure framework for building MCP servers +- Start your MCP server and connect to it from your favorite MCP client +- Call a simple tool +- Call a tool that requires a secret +- Create an Arcade account +- Call a tool that requires auth + + + + + + +## Install the Arcade CLI + +In your terminal, run the following command to install the `arcade-mcp` package - Arcade's CLI: + + + + +```bash +uv tool install arcade-mcp +``` + +{" "} + + + This will install the Arcade CLI as a [uv + tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it + available system wide. + + + + + + +```bash +pip install arcade-mcp +``` + + + + +## Create Your Server + +In your terminal, run the following command to scaffold a new MCP Server called `my_server`: + +```bash +arcade new my_server +cd my_server/src/my_server +``` + +This generates a Python module with the following structure: + +```bash +my_server/ +├── src/ +│ └── my_server/ +│ ├── __init__.py +│ ├── .env.example +│ └── server.py +└── pyproject.toml +``` + +- **server.py** Entrypoint file with MCPApp and example tools +- **pyproject.toml** Dependencies and project configuration +- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py` + +`server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools: + +- **`greet`**: This tool has a single argument, the name of the person to greet. It requires no secrets or auth +- **`whisper_secret`**: This tool requires no arguments, and will output the last 4 characters of a `MY_SECRET_KEY` secret that you can define in your `.env` file. +- **`get_posts_in_subreddit`**: This tool has a single argument, a subreddit, and will return the latest posts on that subreddit, it requires the user to authorize the tool to perform a read operation on their behalf. + +> If you're having issues with the `arcade` command, please see the [Troubleshooting](#troubleshooting) section. + +## Setup the secrets in your environment + +Secrets are sensitive strings like passwords, API keys, or other tokens that grant access to a protected resource or API. Arcade includes the "whisper_secret" tool that requires a secret key to be set in your environment. If the secret is not set, the tool will return an error. + + + +You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret: + +```env filename=".env" +MY_SECRET_KEY="my-secret-value" +``` + +The generated project includes a `.env.example` file with the secret key name and example value. +You can rename it to `.env` to start using it. + +```bash +mv .env.example .env +``` + + + +You can set the environment variable in your terminal directly with this command: + +```bash +export MY_SECRET_KEY="my-secret-value" +``` + + + + +## Connect to Arcade to unlock authorized tool calling + +Since the Reddit tool accesses information only available to your Reddit account, you'll need to authorize it. For this, you'll need to create an Arcade account and connect to it from the terminal, run: + +```bash +arcade login +``` + +Follow the instructions in your browser, and once you've finished, your terminal will be connected to your Arcade account. + +## Run your MCP Server + +Run your MCP Server using one of the following commands in your terminal: + + + + + +```bash +uv run server.py stdio +``` + + + When using the stdio transport, MCP clients typically launch the MCP server as + a subprocess. Because of this, the server may run in a different environment + and not have access to secrets defined in your local `.env` file. Please refer + to the [create a tool with + secrets](/home/build-tools/create-a-tool-with-secrets) guide for more + information. + + + + + +```bash +uv run server.py http +``` + +For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). + + + For security reasons, Local HTTP servers do not currently support tool-level + authorization and secrets. If you need to use tool-level authorization or + secrets locally, you should use the stdio transport and configure the Arcade + API key and secrets in your MCP connection settings. Otherwise, if you intend + to expose your HTTP MCP server to the public internet with tool-level + authorization and secrets, please follow the [deploying to the cloud with + Arcade Deploy](/home/serve-tools/arcade-deploy) guide or the [on-prem MCP + server](/home/deployment/on-prem-mcp) guide for secure remote deployment. + + + + + +You should see output like this in your terminal: + +```bash +2025-11-03 13:46:11.041 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: greet +2025-11-03 13:46:11.042 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: whisper_secret +2025-11-03 13:46:11.043 | DEBUG | arcade_mcp_server.mcp_app:add_tool:242 - Added tool: get_posts_in_subreddit +INFO | 13:46:11 | arcade_mcp_server.mcp_app:299 | Starting my_server v1.0.0 with 3 tools +``` + +## Configure your MCP Client(s) + +Now you can connect MCP Clients to your MCP server: + + + + + ```bash + # Configure Cursor to use your MCP server with the default transport (stdio) + arcade configure cursor + + # Configure Cursor to use your MCP server with the http transport + arcade configure cursor --transport http + ``` + + + + + ```bash + # Configure VS Code to use your MCP server with the default transport (stdio) + arcade configure vscode + + # Configure VS Code to use your MCP server with the http transport + arcade configure vscode --transport http + ``` + + + + + ```bash + # Configure Claude Desktop to use your MCP server with the default transport (stdio) + arcade configure claude + + # Configure Claude Desktop to use your MCP server with the http transport + arcade configure claude --transport http + ``` + + + + +## Try it out! + +Try calling your tool inside your assistant. + +Here's some prompts you can try: + +- "Get some posts from the r/mcp subreddit" +- "What's the last 4 characters of my secret key?" +- "Greet me as Supreme MCP Master" + + + +## Troubleshooting + +### `arcade` command not found or not working + +If you're getting issues with the `arcade` command, please make sure you did not install it outside of your virtual environment. For example, if your system-wide Python installation older than 3.10, you may need to uninstall arcade from that Python installation in order for the terminal to recognize the `arcade` command installed in your virtual environment. + +### The Reddit tool is not working + +Ensure you run `arcade login` and follow the instructions in your browser to connect to your Arcade account. + +### The Whisper Secret tool is not working + +Ensure you have set the environment variable in your terminal or `.env` file, and that it matches the secret key defined in the `@app.tool` decorator. If you are using the stdio transport, then ensure the environment variable is set in the MCP client's configuration file. + +## Next Steps + +- **Learn how to write a tool with auth**: [Create a tool with auth](/home/build-tools/create-a-tool-with-auth) +- **Learn how to write a tool with secrets**: [Create a tool with secrets](/home/build-tools/create-a-tool-with-secrets) +- **Learn more about the Context object**: [Tools and Context](/home/build-tools/tool-context) +- **Learn how to write tool evaluations**: [Create an evaluation suite](/home/evaluate-tools/create-an-evaluation-suite) to optimize them for LLM usage +- **Learn how to deploy your MCP server**: [Deploy your MCP server](/home/serve-tools/arcade-deploy) \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx b/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx index d5ecbbf58..3f86d1684 100644 --- a/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx +++ b/app/en/home/creating-tools/tool-basics/call-tools-mcp/page.mdx @@ -1,7 +1,323 @@ -# call-tools-mcp +--- +title: "Call tools from MCP clients" +description: "Learn how to call tools from MCP clients" +--- -Documentation coming soon. +import { Steps, Tabs, Callout } from "nextra/components"; -## Overview +# Call tools from MCP clients -This section will contain detailed information about call-tools-mcp. + + + +Configure your MCP clients to call tools from your MCP server. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [Arcade CLI](/home/arcade-cli) +- [An MCP Server](/home/build-tools/create-a-mcp-server) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) + + + + + +- How to configure your MCP clients depending on the transport type. +- How to set the secrets for your MCP server in your client's configuration file. + + + + +## Using the `arcade configure` command + +For popular MCP clients, you can use the `arcade configure` command to configure your MCP client to call your MCP server. This will automatically add the MCP server to your client's configuration file. By default, it will use the stdio transport. You must run this command from the directory of your entrypoint file. + + + + + ```bash + arcade configure cursor + ``` + + + + + ```bash + arcade configure vscode + ``` + + + + + ```bash + arcade configure claude + ``` + + + + +You can customize a lot of the configuration passing options to `arcade configure`. For example, to change the transport type to http, you can pass the `--transport` (or `-t`) option: + + + + + ```bash + arcade configure cursor --transport http + ``` + + + + + ```bash + arcade configure vscode --transport http + ``` + + + + + +Claude Desktop does not currently support the HTTP transport via JSON configuration files. + + + + + +### stdio specific configuration + +If you are using the stdio transport, `arcade configure` will assume the entrypoint file (the script that contains the `MCPApp` instance and calls `app.run()`) to your MCP server is `server.py` and will set the working directory to the path of your entrypoint file. You can override this with the `--entrypoint` (or `-e`) option: + + + Note that the `--entrypoint` accepts only the filename of the entrypoint + file, not the path to the script. + + + When using the stdio transport, `arcade configure` will automatically load the + secrets from the `.env` file at the directory of your entrypoint file into the appropriate + configuration file for your MCP client. + + + + + + ```bash + arcade configure cursor --entrypoint my_server.py + ``` + + + + + ```bash + arcade configure vscode --entrypoint my_server.py + ``` + + + + + ```bash + arcade configure claude --entrypoint my_server.py + ``` + + + + +### HTTP specific configuration + +If you are using the streamable HTTP transport, `arcade configure` will assume the MCP server is running on the default port `8000` and that the MCP server is running locally (in localhost). You can override this with the `--host` (or `-h`) and `--port` (or `-p`) options: + + + + + Run from a different port: + + ```bash + arcade configure cursor -t http --port 8000 + ``` + + If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option: + + ```bash + arcade configure cursor -t http --host arcade + ``` + + + + + Run from a different port: + + ```bash + arcade configure vscode -t http --port 8000 + ``` + + If you want to configure an MCP server running on the Arcade Cloud, you can use the `--host` option: + + ```bash + arcade configure vscode -t http --host arcade + ``` + + + + + +Claude Desktop does not currently support the HTTP transport via JSON configuration files. + + + + + +### Other configuration options + +If you have modified the default configuration of your MCP client, or want to use a profile/workspace specific configuration file, then you can pass the `--config` (or `-c`) option to `arcade configure` to use your custom configuration file: + + + + + ```bash + arcade configure cursor --config /path/to/your/config.json + ``` + + + + + ```bash + arcade configure vscode --config /path/to/your/config.json + ``` + + + + + ```bash + arcade configure claude --config /path/to/your/config.json + ``` + + + + +By default, `arcade configure` will use the current directory as the name of the MCP server. You can override this with the `--name` (or `-n`) option: + + + + + ```bash + arcade configure cursor --name my_server + ``` + + + + + ```bash + arcade configure vscode --name my_server + ``` + + + + + ```bash + arcade configure claude --name my_server + ``` + + + + +## Manually configuring your MCP client + +If your MCP client is not supported by the `arcade configure` command, you can manually add the MCP server to your client's configuration file. + +Each MCP client has a different way of configuring MCP servers. This section covers the most common ways of configuring MCP servers adopted by the most popular MCP clients. However, you may find inconsistencies such as the need to specify the MCP server's type as its transport, or as "local" and "remote". Some MCP clients will use "env" to pass environment variables, while others may use "environment" or "inputs". Use this guide as a conceptual reference, but always refer to your MCP client's documentation for the most up-to-date information. + + + + +When configuring your MCP client using the stdio transport, you need to ensure that the MCP server is called using the right version of Python and within the correct working directory. For example, let's pretend this is your setup: + +- Your virtual environment is located at `/path/to/your/project/.venv` +- Your project is located at `/path/to/your/project` +- The entrypoint to your MCP server is located at `/path/to/your/server.py` +- One of your tools requires the `MY_SECRET_KEY` environment variable to be set. +- Your secrets are stored in the `/path/to/your/project/.env` file + +Then, your MCP client's configuration file should look like this: + +```json +{ + "mcpServers": { + "my_server": { + "command": "/path/to/your/project/.venv/bin/python", + "args": ["/path/to/your/project/server.py", "stdio"], + "env": { + "MY_SECRET_KEY": "my-secret-value" + } + } + } +} +``` + +This will ensure that the command used by the MCP client to start the MCP server is the correct version of Python and that the environment variables are set correctly. + + + + +When configuring your MCP client using the Streamable HTTP transport, ensure the MCP server is started on the correct port and from the correct working directory. For example, if your setup is: + +- Your virtual environment is located at `/path/to/your/project/.venv` +- Your MCP server is located at `/path/to/your/project/server.py` +- Your secrets are stored in the `/path/to/your/project/.env` file + +Activate the virtual environment: + +```bash +source /path/to/your/project/.venv/bin/activate +``` + +run the MCP server using the http transport. The secrets will be loaded from the `.env` file that is located at the directory of your entrypoint file: + +```bash +uv run server.py http +``` + +Then, your MCP client's configuration file should look like this: + +```json +{ + "mcpServers": { + "my_server": { + "url": "http://127.0.0.1:8000", + "transport": "http" + } + } +} +``` + + + For security reasons, Local HTTP servers do not currently support managed + authorization and secrets. If you need to use authorization or secrets, you + should use the stdio transport and configure the Arcade API key and secrets in + your MCP connection settings. If you intend to expose your HTTP MCP server to + the public internet, please follow the [on-prem MCP + server](/home/deployment/on-prem-mcp) guide for secure remote deployment. + + + + \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx b/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx index 580e3b3c1..a0f87c64a 100644 --- a/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx +++ b/app/en/home/creating-tools/tool-basics/compare-server-types/page.mdx @@ -1,7 +1,17 @@ -# compare-server-types +--- +title: "Compare Server Types" +description: "Compare the different types of MCP servers" +--- -Documentation coming soon. +# Compare MCP Server Types -## Overview +Depending on the transport you use and where you want to run your MCP server, Arcade offers different functionalities and features. Below is a comparison of the different server types and their capabilities. -This section will contain detailed information about compare-server-types. +| Transport | Deployment | Tools without requirements | Tools with secrets | Tools with auth (single-user) | Tools with auth (multi-user) | +| --------- | ----------------------------------------------------------------------- | :------------------------: | :----------------: | :---------------------------: | :--------------------------: | +| stdio | local | ✅ | ✅ | ✅ | ❌ | +| http | local ([unprotected](/home/glossary#unprotected-mcp-servers)) | ✅ | ❌ | ❌ | ❌ | +| http | remote ([unprotected](/home/glossary#unprotected-mcp-servers)) | ✅ | ❌ | ❌ | ❌ | +| http | local ([protected](/home/glossary#protected-mcp-servers)) `coming soon` | ✅ | ✅ | ✅ | ✅ | +| http | remote ([protected](/home/glossary#protected-mcp-servers)) | ✅ | ✅ | ✅ | ✅ | +| http | Arcade Cloud | ✅ | ✅ | ✅ | ✅ | \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx b/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx index 412fb1902..7c76600e0 100644 --- a/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx +++ b/app/en/home/creating-tools/tool-basics/create-tool-auth/page.mdx @@ -1,7 +1,338 @@ -# create-tool-auth +--- +title: "Add user authorization to your MCP tools" +description: "Learn how to build custom MCP tools that require user authorization using Arcade, auth providers, and OAuth." +--- -Documentation coming soon. +import { Steps, Tabs, Callout } from "nextra/components"; -## Overview +# Add user authorization to your MCP tools -This section will contain detailed information about create-tool-auth. + + + +Create and use an MCP tool that requires OAuth to access Reddit, prompting users to authorize the action when called. Jump to [Example Code](#example-code) to see the complete code. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) +- [Create an MCP Server](/home/build-tools/create-a-mcp-server) + + + + + +- How auth providers work. +- How to add user authorization to your custom tools with Arcade. +- How to use the Context to make authenticated requests to external APIs. +- How to use the Reddit auth provider to authorize your tool. + + + + +An auth provider is the service that issues and manages the OAuth token your tool uses. It is the identity "source of truth" your tool integrates with to request permissions and obtain OAuth tokens. + +When you create a tool with `requires_auth`, you specify which provider to use. In this example, **`arcade_mcp_server.auth.Reddit` specifies the Reddit auth provider.** + +## How auth providers work during execution + +1. When the tool is invoked, Arcade checks if the user has already authorized the scopes required by the tool. +2. If the tool's requirements are not met, Arcade initiates the provider-specific OAuth flow for the requested scopes. + > 2a). The user is presented with a URL to complete the OAuth challenge. The user will need to visit this URL and log in and explicitly grant consent for the action to be performed on their behalf. This is the "OAuth challenge". + + > 2b). The provider issues the token, and Arcade will securely inject it into the tool's [`Context`](/home/build-tools/tool-context) on its next invocation. The client and the LLM will never see the token. + + > 2c). The tool needs to be re-invoked - this time its requirements will be met. +3. The tool is executed, and uses the token injected into its `Context` to call the provider's API (e.g., `https://oauth.reddit.com`), without the LLM or client ever seeing the token. + +The auth provider defines where the identity lives, what permissions are available (scopes), and how tokens are issued and refreshed. In code, it's the class you pass to `requires_auth` (e.g., `Reddit(scopes=["read"])`) that encodes the OAuth details for that service. + +## Add user authorization to your MCP tools + + + +### Import the necessary modules + +Create a new Python file, e.g., `auth_tools.py`, and import the necessary modules and classes: + +```python showLineNumbers filename="auth_tools.py" +import sys +from typing import Annotated + +import httpx +from arcade_mcp_server import Context, MCPApp +from arcade_mcp_server.auth import Reddit +``` + +### Create the MCP Server + +Create an instance of the `MCPApp` class: + +```python filename="auth_tools.py" +app = MCPApp(name="auth_example", version="1.0.0", log_level="DEBUG") +``` + +### Define your MCP tool + +Now, define your tool using the `@app.tool` decorator and specify the required authorization, in this case, by using [Arcade's Reddit auth provider](/home/auth-providers/reddit). + +Specifying the `requires_auth` parameter in the `@app.tool` decorator indicates that the tool needs user authorization. In this example, we're using the `Reddit` auth provider with the `read` scope: + +```python showLineNumbers filename="auth_tools.py" {1-5} {16} +@app.tool( + requires_auth=Reddit( + scopes=["read"] + ) +) +async def get_posts_in_subreddit( + context: Context, subreddit: Annotated[str, "The name of the subreddit"] +) -> dict: + """Get posts from a specific subreddit""" + # Normalize the subreddit name + subreddit = subreddit.lower().replace("r/", "").replace(" ", "") + + # Prepare the httpx request + # OAuth token is injected into the context at runtime. + # LLMs and MCP clients cannot see or access your OAuth tokens. + oauth_token = context.get_auth_token_or_empty() + headers = { + "Authorization": f"Bearer {oauth_token}", + "User-Agent": "mcp_server-mcp-server", + } + params = {"limit": 5} + url = f"https://oauth.reddit.com/r/{subreddit}/hot" + + # Make the request + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers, params=params) + response.raise_for_status() + + # Return the response + return response.json() +``` + + + +To use this tool, you need to install the Arcade CLI and run 'arcade login' to authenticate: + +```bash +uv tool install arcade-mcp +arcade login +``` + + + +Arcade offers a number of [built-in auth providers](/home/auth-providers), including Slack, Google, and GitHub. You can also require authorization with a custom auth provider, using the `OAuth2` class, a subclass of the `ToolAuthorization` class: + +```python +@app.tool( + requires_auth=OAuth2( + id="your-oauth-provider-id", + scopes=["scope1", "scope2"], + ) +) +``` + + + The `OAuth2` class requires an `id` parameter to identify the auth provider in + the Arcade Engine. For built-in providers like `Slack`, you can skip the `id`. + The Arcade Engine will find the right provider using your credentials. While + you can specify an `id` for built-in providers, only do this for private tools + that won't be shared. + + +### Specify OAuth scopes + +Specify the OAuth scopes you need for your tool. In this example, you already are using the `read` scope, but you can specify multiple scopes for more permissions (like `identity`): + +```python showLineNumbers filename="auth_tools.py" {2} +# Multiple scopes for more permissions +@app.tool(requires_auth=Reddit(scopes=["read", "identity"])) +async def identity_tool(context: Context) -> dict: + """Tool that accesses user identity.""" + pass +``` + + +Scopes are defined by the auth provider, and they vary between providers. Each service exposes its own set of scopes that determine what your tools can access. You'll need to review the provider's documentation to see which scopes are available and what permissions each one grants. + + +### Run the MCP Server + +```python showLineNumbers filename="auth_tools.py" +if __name__ == "__main__": + # Get transport from command line argument, default to "stdio" + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + + print(f"Starting auth example server with {transport} transport") + print("Prerequisites:") + print(" 1. Install: uv tool install arcade-mcp") + print(" 2. Login: arcade login\n") + + # Run the server + # - "stdio" (default): Standard I/O transport + # - "http": HTTP streamable transport + app.run(transport=transport, host="127.0.0.1", port=8000) +``` + +Verify your MCP Server can run successfully by executing the following command in your terminal: + +```bash +uv run auth_tools.py stdio +``` + +## Configure your MCP Client(s) + +Now you can connect your MCP server to apps that support MCP Clients, like AI assistants and IDEs. : + + + + + ```bash + arcade configure claude + ``` + + + + + ```bash + arcade configure cursor + ``` + + + + + ```bash + arcade configure vscode + ``` + + + + +Now restart your MCP Client and try calling your tool. + +### Handle authorization + +Since the tool requires authorization, the first time a user uses it, the user will go through an OAuth flow to authorize the tool to act on their behalf. Once the user has completed the OAuth flow, the tool will need to be re-invoked. See the [how auth providers work during execution](#how-auth-providers-work-during-execution) section for more details. + + + +## How it works + +Arcade manages the OAuth flow, and provides the token via `context.get_auth_token_or_empty()`. Arcade also remembers the user's authorization tokens, so they won't have to go through the authorization process again until the token is revoked by the user. + +### Accessing OAuth tokens + +To get the authorization token, use the `context.get_auth_token_or_empty()` method. + +```python filename="auth_tools.py" +# Get the token (returns empty string if not authenticated) +oauth_token = context.get_auth_token_or_empty() + +# Use token in API requests +headers = { + "Authorization": f"Bearer {oauth_token}", + "User-Agent": "my-app", +} +``` + +### Making Authenticated API Requests + +Use the OAuth token with httpx or other HTTP clients: + +```python filename="auth_tools.py" +import httpx + +async with httpx.AsyncClient() as client: + response = await client.get( + "https://oauth.reddit.com/api/endpoint", + headers={"Authorization": f"Bearer {oauth_token}"} + ) + response.raise_for_status() + return response.json() +``` + +## Security Best Practices + +- Never log tokens: OAuth tokens should never be logged or exposed +- Use appropriate scopes: Request only the scopes your tool actually needs + +## Key takeaways + +- **OAuth Support:** Arcade handles OAuth flows and token management +- **Secure Token Injection:** Tokens are injected into context at runtime +- **Scope Management:** Specify exactly which permissions your tool needs +- **Provider Support:** Multiple OAuth providers available out of the box +- **User Privacy:** LLMs and MCP clients never see OAuth tokens + +## Next steps + +- Try adding more authorized tools +- Explore how to handle different authorization providers and scopes +- Learn how to [build a tool with secrets](/home/build-tools/create-a-tool-with-secrets) + +## Example Code + +```python showLineNumbers filename="auth_tools.py" +#!/usr/bin/env python3 +import sys +from typing import Annotated + +import httpx +from arcade_mcp_server import Context, MCPApp +from arcade_mcp_server.auth import Reddit + +# Create the app +app = MCPApp(name="auth_example", version="1.0.0", log_level="DEBUG") + + +# To use this tool, you need to use the Arcade CLI (uv pip install arcade-mcp) +# and run 'arcade login' to authenticate. +@app.tool(requires_auth=Reddit(scopes=["read"])) +async def get_posts_in_subreddit( + context: Context, subreddit: Annotated[str, "The name of the subreddit"] +) -> dict: + """Get posts from a specific subreddit""" + # Normalize the subreddit name + subreddit = subreddit.lower().replace("r/", "").replace(" ", "") + + # Prepare the httpx request + # OAuth token is injected into the context at runtime. + # LLMs and MCP clients cannot see or access your OAuth tokens. + oauth_token = context.get_auth_token_or_empty() + headers = { + "Authorization": f"Bearer {oauth_token}", + "User-Agent": "mcp_server-mcp-server", + } + params = {"limit": 5} + url = f"https://oauth.reddit.com/r/{subreddit}/hot" + + # Make the request + async with httpx.AsyncClient() as client: + response = await client.get(url, headers=headers, params=params) + response.raise_for_status() + + # Return the response + return response.json() + + +if __name__ == "__main__": + # Get transport from command line argument, default to "stdio" + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + + print(f"Starting auth example server with {transport} transport") + print("Prerequisites:") + print(" 1. Install: uv tool install arcade-mcp") + print(" 2. Login: arcade login\n") + + # Run the server + # - "stdio" (default): Standard I/O transport + # - "http": HTTP streamable transport + app.run(transport=transport, host="127.0.0.1", port=8000) + +``` \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx b/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx index 27de627a4..078cf3625 100644 --- a/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx +++ b/app/en/home/creating-tools/tool-basics/create-tool-secrets/page.mdx @@ -1,7 +1,295 @@ -# create-tool-secrets +--- +title: "Create an MCP tool with secrets" +description: "Learn how to build custom MCP tools that require secrets using Arcade" +--- -Documentation coming soon. +import { Steps, Tabs, Callout } from "nextra/components"; -## Overview +# Create an MCP tool with secrets -This section will contain detailed information about create-tool-secrets. + + + +Build an MCP tool that can read a secret from Context and return a masked confirmation string. Jump to [Example Code](#example-code) to see the complete code. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [Arcade CLI](/home/quickstart) +- [An MCP Server](/home/build-tools/create-a-mcp-server) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) + + + + + +- How to read secrets from environment and `.env` files securely using a tool's Context. +- How to configure secrets in the Arcade Dashboard. + + + + +Secrets are sensitive strings like passwords, API keys, or other tokens that grant access to a protected resource or API. You can also use secrets to provide other static configuration values your tool needs, such as parameters for calling a remote API. + +## Why use secrets in your tools? + +Secrets enable you to securely deploy a function that requires sensitive information at runtime. And while these can be consumed directly from the runtime environment inside your tool function, this becomes very inconvenient, expensive, hard to maintain, and insecure when deploying at scale. + +For example, if your tool requires an API key to use an external service, but only _after_ doing some computationally expensive work, you need to ensure that the API key is present _before_ the computationally expensive work is done. The function below would fail if the API key is not present. + +```python +import os + +def my_tool(task: str) -> str: + result = expensive_computation(task) + + API_KEY = os.getenv("API_KEY") + + # The line below will fail if the API key is not present + success = upload_result_to_service(result, API_KEY) + + if success: + return "Result uploaded successfully" + else: + return "Failed to upload result" +``` + +We can work around this by carefully checking for the API key before doing the computationally expensive work, of course, but this is error prone and difficult to maintain, and you may only become aware of the issue after deploying multiple instances of your server. + +Arcade provides a way to securely store and access secrets inside your tools in a way that is easy to manage across multiple instances of your servers, and that will prevent the tool from running if the secret is not provided. In this guide, you'll learn how to use secrets in your custom Arcade tools. + + + +## Store your secret + +Depending on where you're running your server, you can store your secret in a few different ways. + + + +You can create a `.env` file in the same directory as your entrypoint file (typically `server.py` by default) and add your secret: + +```env filename=".env" +MY_SECRET_KEY="my-secret-value" +``` + +The project includes a `.env.example` file with the secret key name and example value. +You can rename it to `.env` to start using it. + +```bash +mv .env.example .env +``` + + + Using a `.env` file is okay for local development, but you should use + the Arcade Dashboard or Arcade CLI for production deployments. + + + + +You can store your secret in the Arcade Dashboard by: + +- Navigating to the "Secrets" section of the Arcade Dashboard +- Clicking the "Add Secret" button +- Entering the secret ID and value +- Clicking the "Create" button + +This will make the secret available to your MCP server, when deployed to Arcade. + + + The Arcade Dashboard will make the secret available to your MCP server when it is deployed. Secrets set in the Arcade Dashboard are not available to your MCP server when it is running locally. + + + + +You can set the secret in your terminal directly with this command: + +```bash +arcade secret set MY_SECRET_KEY="my-secret-value" +``` + + + The Arcade CLI will make the secret available to your MCP server when it is deployed, because it upserts the secret into the Arcade Cloud. Secrets set in the Arcade CLI are not available to your MCP server when it is running locally. + + + + +You can set the environment variable in your terminal directly with this command: + +```bash +export MY_SECRET_KEY="my-secret-value" +``` + + + Using environment variables is okay for local development, but you should use + the Arcade Dashboard or Arcade CLI for production deployments. + + + + + +### Using secrets with stdio transport + +When using the stdio transport, MCP clients typically launch the MCP server as a subprocess. Because of this, the server may run in a different environment and not have access to secrets defined in your local `.env` file or your terminal environment variables. + +To ensure your stdio MCP server has access to the secrets, you can either +1. Utilize the [`arcade configure` CLI command](/home/arcade-cli#arcade-configure) to configure your MCP client to pass the secrets to your MCP server, or +2. Manually configure your MCP client to pass the secrets to your MCP server. For example, if you are using Cursor IDE, you can add the following to your `mcp.json` file: + + ```json + { + "mcpServers": { + "simple": { + "command": "uv", + "args": [ + "run", + "--directory", + "/absoulute/path/to/your/entrypoint/file/parent/directory", + "python", + "server.py" + ], + "env": { + "MY_SECRET_KEY": "my-secret-value" + } + } + } + } + ``` + +This will make the secret available to your MCP server when the MCP client starts the subprocess. +Note that the specific key name may vary depending on the MCP client you are using. + +### Define your tool and access the secret + + + This is only an illustrative example of how Arcade will ensure that the secret + is present before the tool is executed. In a real world application, you would + use this secret to store sensitive information like API keys, database + credentials, etc, and not to simply print a confirmation string. + + +In your [MCP Server](/home/build-tools/create-a-mcp-server), create a new tool that uses the secret: + +- Use the `requires_secrets` parameter to declare which secrets your tool needs (`"SECRET_KEY"` in this example). +- The tool's Context object has a `get_secret` method that you can use to access the secret value. + +```python filename="secrets.py" showLineNumbers highlightLines={2,4,7} +@app.tool( + requires_secrets=["SECRET_KEY"], # declare we need SECRET_KEY +) +def use_secret(context: Context) -> str: + """Read SECRET_KEY from context and return a masked confirmation string.""" + try: + value = context.get_secret("SECRET_KEY") + masked = value[:2] + "***" if len(value) >= 2 else "***" + return f"Got SECRET_KEY of length {len(value)} -> {masked}" + except ValueError as e: + return f"Error getting secret: {e}" +``` + +When your tool is executed, it will return: `"Got SECRET_KEY of length..."`. In a real world application, you would use this secret to connect to a remote database, API, etc. + + + + + +**Security Best Practices** + +- **Never log secret values:** Always mask or truncate when displaying +- **Declare requirements:** Use `requires_secrets` to document dependencies +- **Handle missing secrets:** Use try/except when accessing secrets +- **Use descriptive names:** Make it clear what each secret is for + + + +## Key Concepts + +- **Secure Access:** Secrets are accessed through context, not imported directly +- **Environment Integration:** Works with both environment variables and .env files +- **Error Handling:** Always handle the case where a secret might be missing +- **Masking:** Never expose full secret values in logs or return values +- **Declaration:** Use `requires_secrets` to make dependencies explicit + +## Example Code + +### Environment Variables + +```env filename=".env" +SECRET_KEY="supersecret" +``` + + + +For the code to work, you must define your environment variables locally or in a `.env` file. + + + +```python filename="secrets.py" +#!/usr/bin/env python3 +import sys + +from arcade_mcp_server import Context, MCPApp + +# Create the MCP application +app = MCPApp( + name="secrets_example", + version="1.0.0", + instructions="Example server demonstrating secrets usage", +) + + +@app.tool( + requires_secrets=["SECRET_KEY"], # declare we need SECRET_KEY +) +def use_secret(context: Context) -> str: + """Read SECRET_KEY from context and return a masked confirmation string.""" + try: + value = context.get_secret("SECRET_KEY") + masked = value[:2] + "***" if len(value) >= 2 else "***" + return f"Got SECRET_KEY of length {len(value)} -> {masked}" + except ValueError as e: + return f"Error getting secret: {e}" + + +if __name__ == "__main__": + # Get transport from command line argument, default to "stdio" + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + + # Run the server + app.run(transport=transport, host="127.0.0.1", port=8000) +``` + +### Run your MCP server + + + + +```bash +uv run secrets.py stdio +``` + + + + +```bash +uv run secrets.py http +``` + +For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). + + + For security reasons, Local HTTP servers do not currently support tool-level + authorization and secrets. If you need to use tool-level authorization or secrets locally, you + should use the stdio transport and configure the Arcade API key and secrets in + your MCP connection settings. Otherwise, if you intend to expose your HTTP MCP server to + the public internet with tool-level authorization and secrets, please follow the [deploying to the cloud with Arcade Deploy](/home/serve-tools/arcade-deploy) guide or the [on-prem MCP + server](/home/deployment/on-prem-mcp) guide for secure remote deployment. + + + + + \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx b/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx index e53ec9998..ac5905e62 100644 --- a/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx +++ b/app/en/home/creating-tools/tool-basics/migrate-toolkits/page.mdx @@ -1,7 +1,301 @@ -# migrate-toolkits +--- +title: "Migrate from toolkits to MCP servers" +description: "Learn how to migrate your existing Arcade toolkit to the new MCP Server framework" +--- -Documentation coming soon. +import { Steps, Callout } from "nextra/components"; -## Overview +# Migrate from toolkits to MCP servers -This section will contain detailed information about migrate-toolkits. +This guide helps you migrate your existing Arcade toolkit to the new MCP Server framework. The `arcade-tdk` package has been deprecated in favor of `arcade-mcp-server`, and the `arcade-ai` CLI has been replaced by `arcade-mcp`. + + + If you're building a new MCP server from scratch, check out the [Create an MCP + Server](/home/build-tools/create-a-mcp-server) guide instead. + + + If you're migrating an existing toolkit to a new MCP server, it may be useful + to read through our quickstart guide to get a sense of the new MCP Server + framework: [Create an MCP Server](/home/build-tools/create-a-mcp-server) + + +## Understanding the changes + +Before migrating, it's helpful to understand what has changed: + +### Terminology updates + +- **Workers** are now called **servers** or **MCP servers** +- **Toolkits** are now called **servers**, **MCP servers**, or **tools** depending on the context + +### Package changes + +- **arcade-ai** (old CLI) → **arcade-mcp** (new CLI) +- **arcade-tdk** (old tool development kit) → **arcade-mcp-server** (new MCP Server framework) + +The new `arcade-mcp-server` framework should feel familiar if you've used `arcade-tdk`, but there are important differences to be aware of. + + + +## Update your dependencies + +Open your `pyproject.toml` file and update the dependencies: + +### Replace the main dependency + +Replace `arcade-tdk` with `arcade-mcp-server`: + +```toml +[project] +dependencies = [ + "arcade-mcp-server>=1.4.0,<2.0.0", + # ... other dependencies +] +``` + +### Update development dependencies + +If your toolkit used `arcade-ai` or `arcade-serve` as development dependencies, replace them with `arcade-mcp[all]`: + +```toml +[project.optional-dependencies] +dev = [ + "arcade-mcp[all]>=1.3.0,<2.0.0", + # ... other dev dependencies +] +``` + +### Install the updated dependencies + +Run the following command to install the updated dependencies and development dependencies: + +```bash +uv sync --extra dev +``` + +## Update your imports + +Replace all imports from `arcade-tdk` with imports from `arcade-mcp-server`. Most import paths have remained the same or have only slight variations: + +### Auth imports + +```python +# Before +from arcade_tdk.auth import Google + +# After +from arcade_mcp_server.auth import Google +``` + +### Tool decorator + +```python +# Before +from arcade_tdk import tool + +# After +from arcade_mcp_server import tool +``` + +### Error handling + +```python +# Before +from arcade_tdk.errors import ToolExecutionError + +# After +from arcade_mcp_server.exceptions import ToolExecutionError +``` + +### Context object + +Replace `ToolContext` with `Context`: + +```python +# Before +from arcade_tdk import ToolContext + +@tool +def my_tool(context: ToolContext) -> str: + """My tool that uses context""" + return "Hello" + +# After +from arcade_mcp_server import Context + +@tool +def my_tool(context: Context) -> str: + """My tool that uses context""" + return "Hello" +``` + + + The `ToolContext` class is no longer used. Make sure to replace all instances + of `ToolContext` with `Context` in your tool functions. + + +## Create an entrypoint file + +Previously, you would run your toolkit using the `arcade serve` CLI command. Now, you need to create an entrypoint file that runs your MCP server. This allows you to define your own startup and teardown logic for your MCP server. + +An entrypoint file is a Python file that creates and runs an `MCPApp` when invoked. `MCPApp` is the developer-facing API for creating and managing your MCP server. + +### Option 1: Use the tool decorator + +You can register tools directly on the app using the `@app.tool` decorator: + +```python +#!/usr/bin/env python3 +"""My MCP Server""" + +import sys +from arcade_mcp_server import MCPApp + +app = MCPApp(name="my_server", version="1.0.0") + +@app.tool +def echo_hello() -> str: + """Tool that just says hello""" + return "Hello" + +@app.tool +def echo_goodbye() -> str: + """Tool that just says goodbye""" + return "Goodbye" + +if __name__ == "__main__": + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + app.run(transport=transport) +``` + +### Option 2: Register tools explicitly + +You can also use the standalone `@tool` decorator and register tools explicitly: + +```python +#!/usr/bin/env python3 +"""My MCP Server""" + +import sys +from arcade_mcp_server import MCPApp, tool + +@tool +def echo_hello() -> str: + """Tool that just says hello""" + return "Hello" + +@tool +def echo_goodbye() -> str: + """Tool that just says goodbye""" + return "Goodbye" + +app = MCPApp(name="my_server", version="1.0.0") +app.add_tool(echo_hello) +app.add_tool(echo_goodbye) + +if __name__ == "__main__": + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + app.run(transport=transport) +``` + +### Option 3: Register tools from modules + +If your old toolkit had many tools, you may want to use the `add_tools_from_module` method to register all your tools at once: + +```python +#!/usr/bin/env python3 +"""My MCP Server""" + +import sys +import my_module_with_tools + +from arcade_mcp_server import MCPApp + +app = MCPApp(name="my_server", version="1.0.0") +app.add_tools_from_module(my_module_with_tools) + +if __name__ == "__main__": + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + app.run(transport=transport) +``` + + + For large toolkits with many tools, using `add_tools_from_module` is the + recommended approach. This keeps your entrypoint file clean and maintainable. + + +## Run your MCP server + +Replace the old `arcade serve` command with direct execution of your entrypoint file: + +```bash +# Before +arcade serve + +# After +uv run server.py +``` + +You can specify the transport type as a command line argument: + +```bash +# Run with stdio transport (default) +uv run server.py stdio + +# Run with HTTP transport +uv run server.py http +``` + +## Update deployment configuration + +The `arcade deploy` command still exists for deploying MCP servers, but the deployment process has been simplified. + +### Before (with toolkits) + +Previously, you would deploy your toolkit using: + +```bash +arcade deploy +``` + +And configure your deployment with a `worker.toml` file. + +### After (with MCP servers) + +You still use `arcade deploy`, but you no longer need a `worker.toml` file: + +```bash +arcade deploy +``` + +The deployment configuration is now inferred from your `MCPApp` and project structure. + + + You're no longer deploying a "worker" you're deploying an MCP server. The + deployment process has been streamlined to require less configuration. + + + + +## Quick reference + +Here's a quick reference table for common changes: + +| Old (toolkit) | New (MCP server) | +| -------------------------------------------------- | ------------------------------------------------------------- | +| `arcade-tdk` | `arcade-mcp-server` | +| `arcade-ai` | `arcade-mcp` | +| `arcade serve` | `uv run server.py` | +| `from arcade_tdk import tool` | `from arcade_mcp_server import tool` | +| `from arcade_tdk import ToolContext` | `from arcade_mcp_server import Context` | +| `from arcade_tdk.errors import ToolExecutionError` | `from arcade_mcp_server.exceptions import ToolExecutionError` | +| `worker.toml` | Not needed | + +## Next steps + +After migrating your toolkit to an MCP server: + +- **Test your server**: Run your server locally and verify all tools work correctly +- **Update your CI/CD**: Update any automated workflows to use the new CLI and commands +- **Deploy your server**: Use `arcade deploy` to deploy your MCP server +- **Configure MCP clients**: Connect your server to [MCP clients](/home/build-tools/call-tools-from-mcp-clients) like Claude Desktop, Cursor, or VS Code diff --git a/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx b/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx index 02a6fbf44..92574b4d5 100644 --- a/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx +++ b/app/en/home/creating-tools/tool-basics/organize-mcp-tools/page.mdx @@ -1,7 +1,208 @@ -# organize-mcp-tools +--- +title: "Organize your MCP server and tools" +description: "Learn best practices for organizing your MCP server and tools, how to import tools from other packages and how to use them together." +--- -Documentation coming soon. +import { Steps, Tabs, Callout } from "nextra/components"; -## Overview +# Organize your MCP server and tools -This section will contain detailed information about organize-mcp-tools. + + + +Learn best practices for organizing your MCP server and tools, how to import tools from other packages and how to use them together. Jump to [Example Code](#example-code) to see the complete code. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [An MCP Server](/home/build-tools/create-a-mcp-server) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) + + + + + +- How to define tools in separate files and import them +- How to import tools from other Arcade packages +- How to use `@app.tool` decorators and imported tools together + + + + +## Project Structure + +We recommend keeping your MCP server file and tools in separate files in a `tools` directory like so: + +```bash + my_server/ + ├── src/ + │ └── my_server/ + │ ├── .env + │ ├── server.py # Entrypoint file with your MCPApp + │ ├── tools/ + │ │ ├── __init__.py + │ │ ├── math_tools.py # @tool decorated functions + │ │ └── text_tools.py # @tool decorated functions + │ ├── pyproject.toml + │ └── README.md + └── pyproject.toml +``` + +## Defining tools + +You can use the `@app.tool` decorator to define your tools in your MCP server file directly on the MCP server app object (`MCPApp`) like this: + +```python filename="server.py" +@app.tool +def server_info() -> Annotated[dict, "Information about this server"]: + """Return information about this MCP server.""" + return { + "name": "Organized Server", + "version": "1.0.0", + "description": "Demonstrates modular tool organization", + "total_tools": 6, # 4 imported + 2 defined here + } +``` + +However, if you need to define more than a few tools, this can make your MCP server file longer and harder to read and maintain. Instead, you can define your tools in separate files and import them. + +## Importing tools + +You can import tools from separate files like this: + +```python filename="server.py" +from tools.math_tools import add, multiply +from tools.text_tools import capitalize_string, word_count +``` + +You could also import specific tools from Arcade PyPI packages: + +```python filename="server.py" +# This is a prebuilt Arcade server - `pip install arcade-gmail` +from arcade_gmail.tools import list_emails +``` + +You can also import whole modules that contain tools like this: + +```python filename="server.py" +# This is a prebuilt Arcade server - `pip install arcade-reddit` +import arcade_reddit +``` + +Add imported tools explicitly to the `MCPApp` instance like this: + +```python filename="server.py" +app.add_tool(add) +app.add_tool(list_emails) +app.add_tools_from_module(arcade_reddit) +``` + +## Key takeaways + +- Keep your MCP server file clean and readable by defining tools in separate files +- Store your tools in a `tools` directory in your project alongside your MCP server file +- You can import tools from other Arcade packages and your own files +- Add imported tools explicitly to the MCP server app object + +## Example Code + + +```python filename="server.py" +#!/usr/bin/env python3 + +import sys +from typing import Annotated + +from arcade_mcp_server import MCPApp + +# Import tools from our mock 'tools' directory +# In a real project, these could come from actual separate files +from tools.math_tools import add, multiply +from tools.text_tools import capitalize_string, word_count + +# In a real project, you could import from Arcade PyPI packages - +# e.g. `pip install arcade-gmail` +# import arcade_gmail + +# Create the MCP application +app = MCPApp( + name="organized_server", + version="1.0.0", + instructions="Example server demonstrating modular tool organization", +) + +# Method 1: Add imported tools explicitly +app.add_tool(add) +app.add_tool(multiply) +app.add_tool(capitalize_string) +app.add_tool(word_count) +# app.add_tools_from_module(arcade_gmail) + + +# Method 2: Define tools directly on the app +@app.tool +def server_info() -> Annotated[dict, "Information about this server"]: + """Return information about this MCP server.""" + return { + "name": "Organized Server", + "version": "1.0.0", + "description": "Demonstrates modular tool organization", + "total_tools": 6, # 4 imported + 2 defined here + } + + +@app.tool +def combine_results( + text: Annotated[str, "Text to process"], + add_num: Annotated[int, "Number to add"], + multiply_num: Annotated[int, "Number to multiply"], +) -> Annotated[dict, "Combined results from multiple tools"]: + """Demonstrate using multiple tools together.""" + return { + "original_text": text, + "capitalized": capitalize_string(text), + "word_count": word_count(text), + "math_result": multiply(add(5, add_num), multiply_num), + } + + +if __name__ == "__main__": + # Check if stdio transport was requested + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + + print(f"Starting {app.name} v{app.version}") + print(f"Transport: {transport}") + print("Setting up database...") + # simulate a database setup + print("Database setup complete") + + # Run the server + app.run(transport=transport, host="127.0.0.1", port=8000) +``` + +### Run your MCP server + + + + +```bash +uv run server.py +``` + + + + +```bash +uv run server.py http +``` + +For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). + + + + diff --git a/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx b/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx index f35802fec..a5fba8974 100644 --- a/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx +++ b/app/en/home/creating-tools/tool-basics/runtime-data-access/page.mdx @@ -1,7 +1,296 @@ -# runtime-data-access +--- +title: "Context and MCP tools" +description: "What Arcade's Tool Context is and how to use it." +--- -Documentation coming soon. +import { Callout, Tabs } from "nextra/components"; -## Overview +# Understanding `Context` and tools -This section will contain detailed information about runtime-data-access. +The `Context` class is used by tools for both runtime capabilities and tool-specific data access. Tools receive a populated `Context` instance as a parameter. Tools should not create `Context` instances directly. + + + + +Understand how to use the `Context` object to access runtime capabilities and tool-specific data. + + + + + +1. Tool-specific data that can be accessed using the `Context` object: + - Access OAuth token via `context.get_auth_token_or_empty` + - Access secrets via `context.get_secret` + - Access user_id via `context.user_id` +1. Runtime capabilities that can be accessed using the `Context` object: + - Log messages via `context.log` + - Request LLM sampling via `context.sampling` + - Request user elicitation via `context.ui.elicit` + - Report progress via `context.progress.report` + + + +## How `Context` Works + +When a tool that requires authorization is invoked, the MCP server automatically: + +1. Creates an instance of `Context` and populates it with the runtime capabilities and tool-specific data +2. Passes this object to your tool's first parameter named "context" + +You can then use the `Context` object to make requests to external APIs that require an OAuth token. + +Let's walk through an example (or skip to [the full code](#example-code)). + +## Context Features + +### Tool-Specific Data + +#### Tool secrets + +Specify required secrets using the `requires_secrets` argument of the `@tool` decorator and access them securely using the `get_secret` method: + +```python +@tool(requires_secrets=["DATABASE_URL", "API_KEY"]) +async def my_tool(context: Context) -> str: + try: + api_key = context.get_secret("API_KEY") + except ValueError: + # Handle missing secret + return "Do something interesting with the secret" +``` + +#### OAuth token + +Specify required authorization using the `requires_auth` argument of the `@tool` decorator and access the OAuth token securely using the `get_auth_token_or_empty` method: + +```python +@tool(requires_auth=ClickUp()) +async def my_tool(context: Context) -> str: + oauth_token = context.get_auth_token_or_empty() + + return "Do something interesting with the OAuth token" +``` + +#### User Info + +Access information about the user that authorized the tool using the `authorization.user_info` attribute. Note that this is only available if the tool's auth provider supports it (e.g., the LinkedIn auth provider provides the user ID): + +```python +user_info = context.authorization.user_info +``` + +### Runtime Capabilities + +#### Logging + +[Logging in MCP](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging) provides a standardized channel for servers to emit structured, leveled messages to clients. Logging is useful for observability, debugging, and user feedback during tool execution. + +You can send log messages at different levels using the `log` attribute of the `Context` object like this: + +```python +await context.log.debug("Debug message") +await context.log.info("Information message") +await context.log.warning("Warning message") +await context.log.error("Error message") +await context.log.log("info", "Info message") # equivalent to await context.log.info("Info message") +``` + +#### Sampling + +[Sampling in MCP](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) is a way for servers to request LLM sampling ("completions" or "generations") from language models via clients. This flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities—with no server API keys necessary. + +```python +await context.sampling.create_message(messages, system_prompt) +``` + +#### Elicitation + +[Elicitation in MCP](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) is a way for servers to request additional information from users through the client during interactions. This flow allows clients to maintain control over user interactions and data sharing while enabling servers to gather necessary information dynamically. + +```python +elicitation_schema = {"type": "object", "properties": {"nickname": {"type": "string"}}} + +await context.ui.elicit("What is your nickname?", elicitation_schema) +``` + +#### Progress Reporting + +[Progress reporting in MCP](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) is a way for servers to report progress for long-running operations to clients. + +```python +await context.progress.report(current, total, "Processing...") +``` + +## Example Code + +The following is an example that shows how tools can access runtime features through +`Context`, including logging, secrets, and progress reporting. + +### Environment Variables + +```env +API_KEY="your-secret-key" +DATABASE_URL="postgresql://localhost/mydb" +``` + + + +For the code to work, you must define your environment variables in a `.env` file at the same directory as your entrypoint file. + + + +```python filename="server.py" +#!/usr/bin/env python3 + +import sys +from typing import Annotated + +from arcade_mcp_server import Context, MCPApp + +# Create the MCP application +app = MCPApp( + name="context_example", + version="1.0.0", + instructions="Example server demonstrating Context usage", +) + + +@app.tool(requires_secrets=["API_KEY"]) +async def secure_api_call( + context: Context, + endpoint: Annotated[str, "API endpoint to call"], + method: Annotated[str, "HTTP method (GET, POST, etc.)"] = "GET", +) -> Annotated[str, "API response or error message"]: + """Make a secure API call using secrets from context.""" + + # Access secrets from environment via Context helper + try: + api_key = context.get_secret("API_KEY") + except ValueError: + await context.log.error("API_KEY not found in environment") + return "Error: API_KEY not configured" + + # Log the API call + await context.log.info(f"Making {method} request to {endpoint}") + + # Simulate API call (in real code, use httpx) + return f"Successfully called {endpoint} with API key: {api_key[:4]}..." + + +# Don't forget to add the secret to the .env file or export it as an environment variable +@app.tool(requires_secrets=["DATABASE_URL"]) +async def database_info( + context: Context, table_name: Annotated[str | None, "Specific table to check"] = None +) -> Annotated[str, "Database connection info"]: + """Get database connection information from context.""" + + # Get database URL from secrets + try: + db_url = context.get_secret("DATABASE_URL") + except ValueError: + db_url = "Not configured" + + if table_name: + return f"Database: {db_url}\nChecking table: {table_name}" + + return f"Database: {db_url}" + +@app.tool +async def logging_tool(context: Context, message: Annotated[str, "The message to log"]) -> str: + """Log a message at varying levels.""" + await context.log.log("debug", f"Debug via log.log: {message}") + await context.log.debug(f"Debug via log.debug: {message}") + await context.log.info(f"Info via log.info: {message}") + await context.log.warning(f"Warning via log.warning: {message}") + await context.log.error(f"Error via log.error: {message}") + + return "Logged!" + +@app.tool +async def reporting_progress(context: Context) -> str: + """Report progress back to the client""" + total = 5 + + for i in range(total): + await context.progress.report(i + 1, total=total, message=f"Step {i + 1} of {total}") + + return "All progress reported successfully" + +@app.tool +async def sampling( + context: Context, text: Annotated[str, "The text to be summarized by the client's model"] +) -> str: + """Summarize the text using the client's model.""" + result = await context.sampling.create_message( + messages=text, + system_prompt=( + "You are a helpful assistant that summarizes text. " + "Given a text, you should summarize it in a few sentences." + ), + ) + return result.text + +@app.tool +async def elicit_nickname(context: Context) -> str: + """Ask the end user for their nickname, and then use it to greet them.""" + elicitation_schema = {"type": "object", "properties": {"nickname": {"type": "string"}}} + result = await context.ui.elicit( + "What is your nickname?", + schema=elicitation_schema, + ) + + if result.action == "accept": + return f"Hello, {result.content['nickname']}!" + elif result.action == "decline": + return "User declined to provide a nickname." + elif result.action == "cancel": + return "User cancelled the elicitation." + + return "Unknown response from client" + + +if __name__ == "__main__": + # Check if stdio transport was requested + transport = sys.argv[1] if len(sys.argv) > 1 else "stdio" + + # Run the server + app.run(transport=transport, host="127.0.0.1", port=8000) +``` + +### Run your MCP server + + + + +```bash +uv run server.py +``` + + + + +```bash +uv run server.py http +``` + +For HTTP transport, view your server's API docs at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). + + + + + +## Key Concepts + +- **Context Parameter** Tools can receive a populated `Context` as their first parameter +- **Async Functions** Use `async def` for tools that use runtime context features +- **Secure Secrets** Secrets are accessed through context, not hardcoded +- **Structured Logging** Log at appropriate levels for debugging +- **Progress Updates** Keep users informed during long operations + +### Next Steps + +- [Build a custom tool that requires user authorization](/home/build-tools/create-a-tool-with-auth) +- [Build a custom tool with secrets](/home/build-tools/create-a-tool-with-secrets) \ No newline at end of file diff --git a/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx b/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx index 462900ed0..213ac1e75 100644 --- a/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx +++ b/app/en/home/creating-tools/tool-basics/when-build-tools/page.mdx @@ -1,7 +1,8 @@ -# when-build-tools +--- +title: "When to build tools" +description: "Learn when to build tools" +--- -Documentation coming soon. +# When to build tools -## Overview - -This section will contain detailed information about when-build-tools. +Coming soon! diff --git a/app/en/home/crewai/_meta.tsx b/app/en/home/crewai/_meta.tsx deleted file mode 100644 index 74c33d663..000000000 --- a/app/en/home/crewai/_meta.tsx +++ /dev/null @@ -1,22 +0,0 @@ -import type { MetaRecord } from "nextra"; - -const meta: MetaRecord = { - "*": { - theme: { - breadcrumb: true, - toc: true, - copyPage: true, - }, - }, - "quickstart-python": { - title: "Quickstart (Python)", - }, - "quickstart-typescript": { - title: "Quickstart (Typescript)", - }, - "custom-auth-flow": { - title: "Custom auth flow", - }, -}; - -export default meta; diff --git a/app/en/home/crewai/custom-auth-flow/page.mdx b/app/en/home/crewai/custom-auth-flow/page.mdx deleted file mode 100644 index 7f847a772..000000000 --- a/app/en/home/crewai/custom-auth-flow/page.mdx +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: "Custom Auth Flow with CrewAI" -description: "Learn how to create a custom auth flow with CrewAI" ---- - -import { Steps, Callout } from "nextra/components"; -import ToggleContent from "@/app/_components/toggle-content"; - -## Custom Auth Flow with CrewAI - -In this guide, we will explore how to create a custom auth flow that will be performed before executing Arcade tools within your CrewAI agent team. - -The `ArcadeToolManager`'s built-in authorization and tool execution flows work well for many typical use cases. However, some scenarios call for a tailored approach. By implementing a custom auth flow, you gain flexibility in handling tool authorization. If your use case calls for a unique interface, additional approval steps, or specialized error handling, then this guide is for you. - - - -### Prerequisites - -- [Obtain an Arcade API key](/home/api-keys) - -### Set up your environment - -Install the required package, and ensure your environment variables are set with your Arcade and OpenAI API keys: - -```bash -pip install crewai-arcade -``` - -### Configure API keys - -Provide your Arcade and OpenAI API keys. You can store them in environment variables like so: - -```bash -export ARCADE_API_KEY="your_arcade_api_key" -export OPENAI_API_KEY="your_openai_api_key" -``` - -### Define your custom auth flow - -The custom auth flow defined in the following code snippet is a function that will be called whenever CrewAI needs to call a tool. - -```python -from typing import Any - -from crewai_arcade import ArcadeToolManager - -USER_ID = "{arcade_user_id}" - -def custom_auth_flow( - manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any] -) -> Any: - """Custom auth flow for the ArcadeToolManager - - This function is called when CrewAI needs to call a tool that requires authorization. - Authorization is handled before executing the tool. - This function overrides the ArcadeToolManager's default auth flow performed by ArcadeToolManager.authorize_tool - """ - # Get authorization status - auth_response = manager.authorize(tool_name, USER_ID) - - # If the user is not authorized for the tool, - # then we need to handle the authorization before executing the tool - if not manager.is_authorized(auth_response.id): - print(f"Authorization required for tool: '{tool_name}' with inputs:") - for input_name, input_value in tool_input.items(): - print(f" {input_name}: {input_value}") - # Handle authorization - print(f"\nTo authorize, visit: {auth_response.url}") - # Block until the user has completed the authorization - auth_response = manager.wait_for_auth(auth_response) - - # Ensure authorization completed successfully - if not manager.is_authorized(auth_response.id): - raise ValueError(f"Authorization failed for {tool_name}. URL: {auth_response.url}") - else: - print(f"Authorization already granted for tool: '{tool_name}' with inputs:") - for input_name, input_value in tool_input.items(): - print(f" {input_name}: {input_value}") - - -def tool_manager_callback(tool_manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any]) -> Any: - """Tool executor callback with custom auth flow for the ArcadeToolManager - - ArcadeToolManager's default executor handles authorization and tool execution. - This function overrides the default executor to handle authorization in a custom way and then executes the tool. - """ - custom_auth_flow(tool_manager, tool_name, **tool_input) - return tool_manager.execute_tool(USER_ID, tool_name, **tool_input) -``` - -### Get Arcade tools - -You can now provide the tool manager callback to the `ArcadeToolManager` upon initialization: - -```python -# Provide the tool manager callback to the ArcadeToolManager -manager = ArcadeToolManager(executor=tool_manager_callback) - -# Retrieve the provided tools and/or MCP Servers as CrewAI StructuredTools. -tools = manager.get_tools(tools=["Gmail.ListEmails"], toolkits=["Slack"]) -``` - -### Use tools in your CrewAI agent team - -Create a Crew that uses your tools with the custom auth flow. When the tool is called, your tool manager callback will be called to handle the authorization and then the tool will be executed. - -```python -from crewai import Agent, Crew, Task -from crewai.llm import LLM - -crew_agent = Agent( - role="Main Agent", - backstory="You are a helpful assistant", - goal="Help the user with their requests", - tools=tools, - allow_delegation=False, - verbose=True, - llm=LLM(model="gpt-4o"), -) - -task = Task( - description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", - expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", - agent=crew_agent, - tools=crew_agent.tools, -) - -crew = Crew( - agents=[crew_agent], - tasks=[task], - verbose=True, - memory=True, -) - -result = crew.kickoff() - -print("\n\n\n ------------ Result ------------ \n\n\n") -print(result) -``` - - - - - -```python -from typing import Any - -from crewai import Agent, Crew, Task -from crewai.llm import LLM -from crewai_arcade import ArcadeToolManager - -USER_ID = "{arcade_user_id}" - -def custom_auth_flow( - manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any] -) -> Any: - """Custom auth flow for the ArcadeToolManager - - This function is called when CrewAI needs to call a tool that requires authorization. - Authorization is handled before executing the tool. - This function overrides the ArcadeToolManager's default auth flow performed by ArcadeToolManager.authorize_tool - """ - # Get authorization status - auth_response = manager.authorize(tool_name, USER_ID) - - # If the user is not authorized for the tool, - # then we need to handle the authorization before executing the tool - if not manager.is_authorized(auth_response.id): - print(f"Authorization required for tool: '{tool_name}' with inputs:") - for input_name, input_value in tool_input.items(): - print(f" {input_name}: {input_value}") - # Handle authorization - print(f"\nTo authorize, visit: {auth_response.url}") - # Block until the user has completed the authorization - auth_response = manager.wait_for_auth(auth_response) - - # Ensure authorization completed successfully - if not manager.is_authorized(auth_response.id): - raise ValueError(f"Authorization failed for {tool_name}. URL: {auth_response.url}") - else: - print(f"Authorization already granted for tool: '{tool_name}' with inputs:") - for input_name, input_value in tool_input.items(): - print(f" {input_name}: {input_value}") - - -def tool_manager_callback(tool_manager: ArcadeToolManager, tool_name: str, **tool_input: dict[str, Any]) -> Any: - """Tool executor callback with custom auth flow for the ArcadeToolManager - - ArcadeToolManager's default executor handles authorization and tool execution. - This function overrides the default executor to handle authorization in a custom way and then executes the tool. - """ - custom_auth_flow(tool_manager, tool_name, **tool_input) - return tool_manager.execute_tool(USER_ID, tool_name, **tool_input) - - -manager = ArcadeToolManager(executor=tool_manager_callback) - -tools = manager.get_tools(tools=["Gmail.ListEmails"], toolkits=["Slack"]) - -crew_agent = Agent( - role="Main Agent", - backstory="You are a helpful assistant", - goal="Help the user with their requests", - tools=tools, - allow_delegation=False, - verbose=True, - llm=LLM(model="gpt-4o"), -) - -task = Task( - description="Get the 5 most recent emails from the user's inbox and summarize them and recommend a response for each.", - expected_output="A bulleted list with a one sentence summary of each email and a recommended response to the email.", - agent=crew_agent, - tools=crew_agent.tools, -) - -crew = Crew( - agents=[crew_agent], - tasks=[task], - verbose=True, - memory=True, -) - -result = crew.kickoff() - -print("\n\n\n ------------ Result ------------ \n\n\n") -print(result) -``` - - - -## Next steps - -Now you're ready to integrate Arcade tools with a custom auth flow into your own CrewAI agent team. diff --git a/app/en/home/crewai/quickstart-python/page.mdx b/app/en/home/crewai/quickstart-python/page.mdx deleted file mode 100644 index 4b5421156..000000000 --- a/app/en/home/crewai/quickstart-python/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Python) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using CrewAI with Python. \ No newline at end of file diff --git a/app/en/home/crewai/quickstart-typescript/page.mdx b/app/en/home/crewai/quickstart-typescript/page.mdx deleted file mode 100644 index 92c76c387..000000000 --- a/app/en/home/crewai/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using CrewAI with TypeScript. \ No newline at end of file diff --git a/app/en/home/custom-apps/_meta.tsx b/app/en/home/custom-apps/_meta.tsx deleted file mode 100644 index b56fb9e54..000000000 --- a/app/en/home/custom-apps/_meta.tsx +++ /dev/null @@ -1,8 +0,0 @@ -export default { - "calling-tools-custom-apps-2": "Calling tools in your custom apps", - "authorized-tool-calling": "Authorized Tool Calling", - "auth-status-check": "Checking Authorization Status", - "tool-formats": "Tool formats", - "connect-arcade-llm": "Connecting Arcade tools to your LLM", - "test-tool-performance": "Testing tool performance", -}; diff --git a/app/en/home/custom-apps/auth-status-check/page.mdx b/app/en/home/custom-apps/auth-status-check/page.mdx deleted file mode 100644 index 110951ac4..000000000 --- a/app/en/home/custom-apps/auth-status-check/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# auth-status-check - -Documentation coming soon. - -## Overview - -This section will contain detailed information about auth-status-check. diff --git a/app/en/home/custom-apps/authorized-tool-calling/page.mdx b/app/en/home/custom-apps/authorized-tool-calling/page.mdx deleted file mode 100644 index 155ffc4a3..000000000 --- a/app/en/home/custom-apps/authorized-tool-calling/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# authorized-tool-calling - -Documentation coming soon. - -## Overview - -This section will contain detailed information about authorized-tool-calling. diff --git a/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx b/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx deleted file mode 100644 index 916ded6a0..000000000 --- a/app/en/home/custom-apps/calling-tools-custom-apps-2/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# calling-tools-custom-apps-2 - -Documentation coming soon. - -## Overview - -This section will contain detailed information about calling-tools-custom-apps-2. diff --git a/app/en/home/custom-apps/connect-arcade-llm/page.mdx b/app/en/home/custom-apps/connect-arcade-llm/page.mdx deleted file mode 100644 index 49a1760ef..000000000 --- a/app/en/home/custom-apps/connect-arcade-llm/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# connect-arcade-llm - -Documentation coming soon. - -## Overview - -This section will contain detailed information about connect-arcade-llm. diff --git a/app/en/home/custom-apps/test-tool-performance/page.mdx b/app/en/home/custom-apps/test-tool-performance/page.mdx deleted file mode 100644 index 160b83045..000000000 --- a/app/en/home/custom-apps/test-tool-performance/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# test-tool-performance - -Documentation coming soon. - -## Overview - -This section will contain detailed information about test-tool-performance. diff --git a/app/en/home/custom-apps/tool-formats/page.mdx b/app/en/home/custom-apps/tool-formats/page.mdx deleted file mode 100644 index b8dae2704..000000000 --- a/app/en/home/custom-apps/tool-formats/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# tool-formats - -Documentation coming soon. - -## Overview - -This section will contain detailed information about tool-formats. diff --git a/app/en/home/deployment-hosting/arcade-deploy/page.mdx b/app/en/home/deployment-hosting/arcade-deploy/page.mdx index f47ca9390..422936989 100644 --- a/app/en/home/deployment-hosting/arcade-deploy/page.mdx +++ b/app/en/home/deployment-hosting/arcade-deploy/page.mdx @@ -1,3 +1,165 @@ -# Arcade Deploy +--- +title: "Cloud deployments with Arcade Deploy" +description: "Learn how to deploy a worker with Arcade Deploy" +--- -Deploy your applications using Arcade Deploy. \ No newline at end of file +import { Steps, Tabs, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; + +# Deploying to the cloud with Arcade Deploy + +Running your MCP servers locally is very convenient during development and testing. Once your MCP server is mature, however, you may want to access it from any MCP client, or to facilitate multi-user support. Doing all that from your computer comes with the complexity of running and maintaining a server, handling auth and high availability for all your users and all the integrations you want to support. Arcade Deploy takes care of all that for you. Your MCP server will be registered to Arcade, adding all the tools you created to the larger tool catalog. From there, you can create MCP Gateways to pick and choose which tools you want to use in your MCP clients, which can be from any connected MCP server. + + + + +This guide shows you how to deploy your MCP Server with Arcade Deploy. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) +- [Create an MCP Server](/home/build-tools/create-a-mcp-server) + + + + + +- How to deploy your existing MCP Server to the cloud with the `arcade deploy` CLI command. +- How to create an MCP Gateway to pick and choose which tools you want to use in your MCP clients. +- How to use Arcade clients to call the tools in your MCP Server. + + + + + + + + ```bash + uv tool install arcade-mcp + ``` + + + This will install the Arcade CLI as a [uv tool](https://docs.astral.sh/uv/guides/tools/#installing-tools), making it available system wide. + + + + + + + ```bash + pip install arcade-mcp + ``` + + + + + + +## Create an MCP server using Arcade MCP + +If you have not created an MCP server yet, then follow the steps outlined in [this guide](/home/build-tools/create-a-mcp-server) before deploying. + +## Deploy your MCP Server + +Run the deploy command in the directory where you started your MCP server (containing your `pyproject.toml` file) and specify the relative path to your entrypoint file via the `--entrypoint/-e` option. + +```bash +arcade deploy -e src/my_server/server.py +``` + +You must run the command from the directory containing your `pyproject.toml` file. + + +By default, running `arcade deploy` looks for a file named `server.py` in the current directory as the entrypoint file to your MCP server. If your entrypoint file is in a different directory, then you need to specify the relative path. + +```py +from arcade_mcp_server import MCPApp + +app = MCPApp() + +@app.tool +def echo(phrase: Annotated[str, "The phrase to echo"]) -> str: + """Echo a phrase""" + return phrase + +if __name__ == "__main__": + app.run() +``` + + +It is important that your entrypoint file executes `MCPApp.run()` (or `app.run()` if `app` is of type `MCPApp`) when invoked directly. + +We recommend to do it inside an `if __name__ == "__main__":` statement. + + + +You should see output like the following: + +```bash +Validating user is logged in... +✓ {arcade_user_id} is logged in + +Validating pyproject.toml exists in current directory... +✓ pyproject.toml found at /path/to/your/project/pyproject.toml + +Loading .env file from current directory if it exists... +✓ Loaded environment from /path/to/your/project/.env + +Validating server is healthy and extracting metadata before deploying... +✓ Server started on port 8001 +✓ Server is healthy +✓ Found server name: my_server +✓ Found server version: 1.0.0 +✓ Found 3 tools +✓ Found 1 required secret(s) + +Uploading 1 required secret(s) to Arcade... +✓ Uploading 'MY_SECRET_KEY' with value ending in ...ime! +✓ Secret 'MY_SECRET_KEY' uploaded + +Creating deployment package... +✓ Package created (1.8 KB) + + +⠧ Deployment in progress (this may take a few minutes)... + +Recent logs: + data: {"Timestamp":"2025-10-27T16:03:45.429460682Z","Line":"Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details."} + data: {"Timestamp":"2025-10-27T16:03:45.429466232Z","Line":"[GIN-debug] Listening and serving HTTP on :8002"} + data: {"Timestamp":"2025-10-27T16:03:47.577492621Z","Line":"[GIN] 2025/10/27 - 16:03:47 | 200 | 2.888808ms | 10.30.253.232 | GET \"/worker/health\""} + data: {"Timestamp":"2025-10-27T16:03:48.230570179Z","Line":"INFO: 127.0.0.1:53384 - \"GET /worker/health HTTP/1.1\" 200 OK"} + data: {"Timestamp":"2025-10-27T16:03:48.231072632Z","Line":"[GIN] 2025/10/27 - 16:03:48 | 200 | 4.526797ms | 10.30.253.232 | GET \"/worker/health\""} + + +You can safely exit with Ctrl+C at any time. The deployment will continue normally. + +✓ Deployment successful! Server is running. +``` + +## Manage your MCP servers in Arcade + +Navigate to the [Servers](https://api.arcade.dev/dashboard/servers) page in your Arcade dashboard. From there, you will be able to: + +- Monitor the health status of the server +- Delete the server +- Test and execute all the tools +- Manage users connected to the Auth providers +- Manage the secrets for the server +- Create [MCP Gateways](/home/mcp-gateways) + +## Create an MCP Gateway to call the tools in your MCP Server + +Once the MCP server is deployed to Arcade, all the tools in the server will be available in the [tool catalog](https://api.arcade.dev/dashboard/tools) page in your Arcade dashboard. To call the tools from an MCP client, you first need to [create an MCP Gateway](/home/mcp-gateways) to pick and choose which tools you want to use in your MCP clients. + +When creating an MCP gateway, you can select the tools you want to include in the Gateway from any MCP Servers available to the project, including the one you just deployed. + +## Use Arcade clients to call the tools in your MCP Server + +You can use any of the available [Arcade clients](/references) to call the tools in your MCP Server. When using the clients, you are not required to create an MCP Gateway, as the client will handle the connection to all tools in your Arcade project directly. + + + +Your MCP Server is now deployed and managed by Arcade, and ready to be used in your MCP clients! \ No newline at end of file diff --git a/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx b/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx index 4350b4f3f..4f25bac1f 100644 --- a/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx +++ b/app/en/home/deployment-hosting/cloud-infrastructure/page.mdx @@ -1,3 +1,28 @@ -# Using Arcade's Cloud Infrastructure +--- +title: "Arcade Cloud Infrastructure" +description: "Learn about the infrastructure that powers Arcade Cloud" +--- -Learn how to deploy using Arcade's cloud infrastructure. \ No newline at end of file +# Arcade Cloud Infrastructure + +This page covers the infrastructure that powers Arcade Cloud, and what you might need to know about it. + +## Egress IP Addresses + +Traffic from Arcade Cloud will be existing our infrastructure from the following IP addresses: + +```sh +# Control Plane (Located in the USA) +3.140.92.118 +3.13.58.74 +3.149.34.246 + +# MCP Server Cluster 1 (Located in the USA) +3.150.210.23 +3.135.113.210 +3.131.234.5 +``` + +## VPC Peering + +VPC Peering is available for our enterprise customers upon request. If you are interested in VPC Peering, please [contact us](/home/contact-us). \ No newline at end of file diff --git a/app/en/home/deployment-hosting/configure-engine/page.mdx b/app/en/home/deployment-hosting/configure-engine/page.mdx index 7d71200e9..97b51502f 100644 --- a/app/en/home/deployment-hosting/configure-engine/page.mdx +++ b/app/en/home/deployment-hosting/configure-engine/page.mdx @@ -1,3 +1,689 @@ -# Configure Arcade's Engine +--- +title: "Engine Configuration Templates" +description: "Arcade Engine Configuration Templates" +--- -How to configure Arcade's engine for your deployment. \ No newline at end of file +import { Callout, Tabs } from "nextra/components"; +import TableOfContents from "@/app/_components/table-of-contents"; + +# Engine Configuration + + + This page is for enterprise customers who are self-hosting the Arcade Engine. This is page contains advanced configuration options that are not applicable for most customers. + + +## Getting the Engine + + + + ```bash + brew install ArcadeAI/tap/arcade-engine + ``` + + Run it with: `arcade-engine` + +Troubleshooting: + +```bash +❌ Engine binary not found +``` + +or + +```bash +command not found: arcade-engine +``` + +This means that the Arcade Engine cannot be found in your path. Brew and Apt will automatically add the binary to your path. + +Check that the binary has been properly installed. These are the common installation locations): + +**Brew** + +```bash +ls $HOMEBREW_REPOSITORY/Cellar/arcade-engine//bin/arcade-engine +``` + +**Apt** + +```bash +ls /usr/bin/arcade-engine +``` + +If the binary is found, add it to your path with: + +```bash +export PATH=$PATH:/path/to/your/binary +``` + + + ```bash + wget -qO - https://deb.arcade.dev/public-key.asc | sudo apt-key add - + echo "deb https://deb.arcade.dev/ubuntu stable main" | sudo tee /etc/apt/sources.list.d/arcade-ai.list + sudo apt update + sudo apt install arcade-engine + ``` + + + The docker image for the engine can be pulled with + + ```bash + docker pull ghcr.io/arcadeai/engine:latest + ``` + + The engine can be run with: + + ```bash + docker run -d -p 9099:9099 -v ./engine.yaml:/bin/engine.yaml ghcr.io/arcadeai/engine:latest + ``` + + where config.yaml is the path to the [configuration file](/home/deployment-hosting/configure-engine). + + + +Arcade uses configuration files to manage engine settings and default values. When you install the Arcade Engine, two files are created: +- The `engine.yaml` file for engine configuration. +- The `engine.env` file for environment variables. +Let's explore each file to understand their purpose and how to locate them. + +## Engine configuration file + +The `engine.yaml` file controls Arcade Engine settings. It supports variable expansion so you can integrate secrets and environment values seamlessly. You can customize this file to suit your setup. For more details, check the [Engine Configuration](/home/deployment-hosting/configure-engine) page. + +Choose your installation method to view the default location of `engine.yaml`: + + + + ```bash + $HOMEBREW_REPOSITORY/etc/arcade-engine/engine.yaml + ``` + + + ```bash + /etc/arcade-ai/engine.yaml + ``` + + + ```bash + $HOME/.arcade/engine.yaml + ``` + To manually download the engine.yaml, you can get an example from the [Configuration Templates](/home/deployment-hosting/configure-engine#engineyaml) and add it to `$HOME/.arcade/engine.yaml`. + + + +## Engine environment file + +The `engine.env` file contains default environment variables that power Arcade Engine. You can override these defaults by exporting your own variables or by editing the file directly. + +Select your installation method below to see the default path for `engine.env`: + + + + ```bash + $HOMEBREW_REPOSITORY/etc/arcade-engine/engine.env + ``` + + + ```bash + /etc/arcade-ai/engine.env + ``` + + + ```bash + $HOME/.arcade/engine.env + ``` + To manually download the `engine.env`, refer to the [Configuration Templates](/home/deployment-hosting/configure-engine#engineenv). + + + + +Arcade Engine's configuration is a [YAML file](https://yaml.org/) with the following sections: + + + +## Specify a config file + +To start the Arcade Engine, pass a config file with `-c` or `--config`: + +```bash +arcade-engine -c /path/to/config.yaml +``` + +## Dotenv files + +Arcade Engine automatically loads environment variables from `.env` files in the directory where it was called. Use the `-e` or`--env` flag to specify a path: + +```bash +arcade-engine -e .env.dev -c config.yaml +``` + +## Secrets + +Arcade Engine supports two ways of passing sensitive information like API keys without storing them directly in the config file. + +Environment variables: + +```yaml {5} +topic: + area: + - id: primary + vendor: + api_key: ${env:OPENAI_API_KEY} +``` + +External files (useful in cloud setups): + +```yaml {5} +topic: + area: + - id: primary + vendor: + api_key: ${file:/path/to/secret} +``` + +## API configuration + +HTTP is the supported protocol for Arcade Engine's API. The following configuration options are available: + +- `api.development` _(optional, default: `false`)_ - Enable development mode, with more logging. +- `api.host` _(default: `localhost`)_ - Address to which Arcade Engine binds its server (e.g., `localhost` or `0.0.0.0`) +- `api.port` _(default: `9099`)_ - Port to which Arcade Engine binds its server (e.g., `9099` or `8080`) +- `api.public_host` _(optional)_ - External hostname of the API (e.g., `my-public-host.com`), if it differs from `api.host` (for example, when Arcade Engine is behind a reverse proxy) +- `api.read_timeout` _(optional, default: `30s`)_ - Timeout for reading data from clients +- `api.write_timeout` _(optional, default: `1m`)_ - Timeout for writing data to clients +- `api.idle_timeout` _(optional, default: `30s`)_ - Timeout for idle connections +- `api.max_request_body_size` _(optional, default: `4Mb`)_ - Maximum request body size + +A typical configuration for production looks like: + +```yaml +api: + development: false + host: localhost + port: 9099 +``` + +When the Arcade Engine is hosted in a container or behind a reverse proxy, set `api.public_host` to the external hostname of the API: + +```yaml +api: + development: false + host: localhost + port: 9099 + public_host: my-public-host.com +``` + +For local development, set `api.development = true`. + +## Auth configuration + +Arcade Engine manages auth for [AI tools](/home/auth/auth-tool-calling) and [direct API calls](/home/auth/call-third-party-apis-directly). It supports many built-in [auth providers](/home/sharing-with-end-users/custom-auth), and can also connect to any [OAuth 2.0](/home/sharing-with-end-users/custom-auth/oauth2) authorization server. + +The `auth.providers` section defines the providers that users can authorize with. Each provider must have a unique `id` in the array. There are two ways to configure a provider: + +For [built-in providers](/home/sharing-with-end-users/custom-auth), use the `provider_id` field to reference the pre-built configuration. For example: + +```yaml +auth: + providers: + - id: default-github + description: The default GitHub provider + enabled: true + type: oauth2 + provider_id: github + client_id: ${env:GITHUB_CLIENT_ID} + client_secret: ${env:GITHUB_CLIENT_SECRET} +``` + +For custom OAuth 2.0 providers, specify the full connection details in the `oauth2` sub-section. For full documentation on the custom provider configuration, see the [OAuth 2.0 provider configuration](/home/sharing-with-end-users/custom-auth/oauth2) page. + +You can specify a mix of built-in and custom providers. + +## Cache configuration + +The `cache` section configures the short-lived cache. + + + Configuring the cache is optional. If not configured, the cache will default + to an in-memory cache implementation suitable for a single-node Arcade Engine + deployment. + + +The `cache` section has the following configuration options: + +- `api_key_ttl` _(optional, default: `10s`)_ - The time-to-live for API keys in the cache + +Two cache implementations are available: + +- `in_memory` - _(default)_ An in-memory cache implementation suitable for a single-node Arcade Engine deployment. +- `redis` - A Redis cache implementation suitable for a multi-node Arcade Engine deployment: + +```yaml +cache: + api_key_ttl: 10s + redis: + addr: "localhost:6379" + password: "" + db: 0 +``` + +## Security configuration + +The `security` section configures the root encryption keys that the Arcade Engine uses to encrypt and decrypt data at rest. See the [storage configuration](#storage-configuration) section below to configure where data is stored. + +A typical configuration looks like this: + +```yaml +security: + root_keys: + - id: key1 + default: true + value: ${env:ROOT_KEY_1} + - id: key2 + value: ${env:ROOT_KEY_2} +``` + +Keys should be a long random string of characters. For example: + +```bash +openssl rand -base64 32 +``` + +### Default root key + +When you [install Arcade Engine locally](/home/deployment-hosting/configure-engine), an `engine.env` file is created with a default root key: + +```bash +# Encryption keys (change this when deploying to production) +ROOT_KEY_1=default-key-value +``` + +This default value can only be used in development mode (see [API configuration](#api-configuration) above). + + + You **must** replace the value of `ROOT_KEY_1` in `engine.env` before + deploying to production. + + +## Storage configuration + +The `storage` section configures the storage backend that the Arcade Engine uses to store persistent data. + +There are three storage implementations available: + +- `in_memory` - _(default)_ An in-memory database, suitable for testing. +- `sqlite` - A SQLite file on disk, suitable for local development: + +```yaml +storage: + sqlite: + # Stores DB in ~/.arcade/arcade-engine.sqlite3 + connection_string: "@ARCADE_HOME/arcade-engine.sqlite3" +``` + +- `postgres` - A PostgreSQL database, suitable for production: + +```yaml +storage: + postgres: + user: ${env:POSTGRES_USER} + password: ${env:POSTGRES_PASSWORD} + host: ${env:POSTGRES_HOST} + port: ${env:POSTGRES_PORT} + db: ${env:POSTGRES_DB} + sslmode: require +``` + +## Telemetry configuration + +Arcade supports logs, metrics, and traces with [OpenTelemetry](https://opentelemetry.io/). + +If you are using the Arcade Engine locally, you can set the `environment` field to `local`. This will only output logs to the console: + +```yaml +telemetry: + environment: local + logging: + # debug, info, warn, error, fatal + level: debug + encoding: console +``` + +To connect to OpenTelemetry compatible collectors, set the necessary [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) in the `engine.env` file. +`environment` and `version` are fields that are added to the telemetry attributes, which can be filtered on later. + +```yaml +telemetry: + environment: prod + logging: + level: info + encoding: console +``` + +### Notes + +- The Engine service name is set to `arcade_engine` +- Traces currently cover the `/v1/health` endpoints, as well as authentication attempts + +## Tools configuration + +Arcade Engine orchestrates [tools](/home/use-tools/tools-overview) that AI models can use. + +The `tools.directors` section configures the mcp servers that are available to service tool calls: + +```yaml +tools: + directors: + - id: default + enabled: true + max_tools: 64 + workers: + - id: local_worker + enabled: true + http: + uri: "http://localhost:8002" + timeout: 30 + retry: 3 + secret: ${env:ARCADE_WORKER_SECRET} +``` + +When an MCP server is added to an enabled director, all of the tools hosted by that MCP server will be available to the model and through the Arcade API. + +### HTTP MCP Server configuration + +The `http` sub-section configures the HTTP client used to call the MCP Server's tools: + +- `uri` _(required)_ - The base URL of the MCP Server's tools +- `secret` _(required)_ - Secret used to authenticate with the MCP Server +- `timeout` _(optional, default: `30s`)_ - Timeout for calling the MCP Server's tools +- `retry` _(optional, default: `3`)_ - Number of times to retry a failed tool call + + + MCP Servers must be configured with a `secret` that is used to authenticate with + the MCP Server. This ensures that MCP Servers are not exposed to the public internet + without security. + +If `api.development = true`, the secret will default to `"dev"` for local development **only**. In production, the secret must be set to a random value. + + + +## Config file version history + +- 1.0: [Full example](https://raw.githubusercontent.com/ArcadeAI/docs/refs/heads/main/examples/code/home/configuration/engine/full_config.1.0.yaml) and [schema](https://raw.githubusercontent.com/ArcadeAI/schemas/refs/heads/main/engine/config/1.0/schema.json) + + +## Engine Config Templates + +### engine.yaml + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json +$schema: https://raw.githubusercontent.com/ArcadeAI/schemas/main/engine/config/1.0/schema.json + +api: + development: ${env:API_DEVELOPMENT} + host: ${env:ARCADE_API_HOST} + port: ${env:ARCADE_API_PORT} + # Optionally set public_host, in case the Arcade Engine is hosted in a container or behind a reverse proxy + #public_host: ${env:ARCADE_API_PUBLIC_HOST} + +auth: + providers: + - id: default-atlassian + description: "The default Atlassian provider" + enabled: false + type: oauth2 + provider_id: atlassian + client_id: ${env:ATLASSIAN_CLIENT_ID} + client_secret: ${env:ATLASSIAN_CLIENT_SECRET} + + - id: default-discord + description: "The default Discord provider" + enabled: false + type: oauth2 + provider_id: discord + client_id: ${env:DISCORD_CLIENT_ID} + client_secret: ${env:DISCORD_CLIENT_SECRET} + + - id: default-dropbox + description: "The default Dropbox provider" + enabled: false + type: oauth2 + provider_id: dropbox + client_id: ${env:DROPBOX_CLIENT_ID} + client_secret: ${env:DROPBOX_CLIENT_SECRET} + + - id: default-github + description: "The default GitHub provider" + enabled: false + type: oauth2 + provider_id: github + client_id: ${env:GITHUB_CLIENT_ID} + client_secret: ${env:GITHUB_CLIENT_SECRET} + + - id: default-google + description: "The default Google provider" + enabled: false + type: oauth2 + provider_id: google + client_id: ${env:GOOGLE_CLIENT_ID} + client_secret: ${env:GOOGLE_CLIENT_SECRET} + + - id: default-linkedin + description: "The default LinkedIn provider" + enabled: false + type: oauth2 + provider_id: linkedin + client_id: ${env:LINKEDIN_CLIENT_ID} + client_secret: ${env:LINKEDIN_CLIENT_SECRET} + + - id: default-microsoft + description: "The default Microsoft provider" + enabled: false + type: oauth2 + provider_id: microsoft + client_id: ${env:MICROSOFT_CLIENT_ID} + client_secret: ${env:MICROSOFT_CLIENT_SECRET} + + - id: default-reddit + description: "The default Reddit provider" + enabled: false + type: oauth2 + provider_id: reddit + client_id: ${env:REDDIT_CLIENT_ID} + client_secret: ${env:REDDIT_CLIENT_SECRET} + + - id: default-slack + description: "The default Slack provider" + enabled: false + type: oauth2 + provider_id: slack + client_id: ${env:SLACK_CLIENT_ID} + client_secret: ${env:SLACK_CLIENT_SECRET} + + - id: default-spotify + description: "The default Spotify provider" + enabled: false + type: oauth2 + provider_id: spotify + client_id: ${env:SPOTIFY_CLIENT_ID} + client_secret: ${env:SPOTIFY_CLIENT_SECRET} + + - id: default-twitch + description: "The default Twitch provider" + enabled: false + type: oauth2 + provider_id: twitch + client_id: ${env:TWITCH_CLIENT_ID} + client_secret: ${env:TWITCH_CLIENT_SECRET} + + - id: default-x + description: "The default X provider" + enabled: false + type: oauth2 + provider_id: x + client_id: ${env:X_CLIENT_ID} + client_secret: ${env:X_CLIENT_SECRET} + + - id: default-zoom + description: "The default Zoom provider" + enabled: false + type: oauth2 + provider_id: zoom + client_id: ${env:ZOOM_CLIENT_ID} + client_secret: ${env:ZOOM_CLIENT_SECRET} + +llm: + models: + - id: my-openai-model-provider + openai: + api_key: ${env:OPENAI_API_KEY} + #- id: my-anthropic-model-provider + # anthropic: + # api_key: ${env:ANTHROPIC_API_KEY} + # - id: my-ollama-model-provider + # openai: + # base_url: http://localhost:11434 + # chat_endpoint: /v1/chat/completions + # model: llama3.2 + # api_key: ollama + #- id: my-groq-model-provider + # openai: + # base_url: 'https://api.groq.com/openai/v1' + # api_key: ${env:GROQ_API_KEY} + +security: + root_keys: + - id: key1 + default: true + value: ${env:ROOT_KEY_1} + +storage: + postgres: + user: ${env:POSTGRES_USER} + password: ${env:POSTGRES_PASSWORD} + host: ${env:POSTGRES_HOST} + port: ${env:POSTGRES_PORT} + db: ${env:POSTGRES_DB} + sslmode: require + +telemetry: + environment: ${env:TELEMETRY_ENVIRONMENT} + logging: + # debug, info, warn, error + level: ${env:TELEMETRY_LOGGING_LEVEL} + encoding: ${env:TELEMETRY_LOGGING_ENCODING} + +tools: + directors: + - id: default + enabled: true + max_tools: 64 + workers: + - id: worker + enabled: true + http: + uri: ${env:ARCADE_WORKER_URI} + timeout: 30 + retry: 3 + secret: ${env:ARCADE_WORKER_SECRET} +``` + +### engine.env + +```bash +### Engine configuration ### +API_DEVELOPMENT=true +ARCADE_API_HOST=localhost +ARCADE_API_PORT=9099 +ANALYTICS_ENABLED=true + +# Encryption keys (change this when deploying to production) +ROOT_KEY_1=default-key-value + +### Model Provider API keys ### +# OPENAI_API_KEY= +# ANTHROPIC_API_KEY= +# GROQ_API_KEY= + + +### Security configuration ### +ROOT_KEY_1= + + +### Storage configuration ### +# POSTGRES_USER= +# POSTGRES_PASSWORD= +# POSTGRES_HOST= +# POSTGRES_PORT= +# POSTGRES_DB= + + +### Telemetry (OTEL) configuration ### +TELEMETRY_ENVIRONMENT=local +TELEMETRY_LOGGING_LEVEL=debug +TELEMETRY_LOGGING_ENCODING=console + + +### Worker Configuration ### +ARCADE_WORKER_URI=http://localhost:8002 +ARCADE_WORKER_SECRET=dev + + +# OAuth Providers +ATLASSIAN_CLIENT_ID="" +ATLASSIAN_CLIENT_SECRET= + +DISCORD_CLIENT_ID="" +DISCORD_CLIENT_SECRET= + +DROPBOX_CLIENT_ID="" +DROPBOX_CLIENT_SECRET= + +GITHUB_CLIENT_ID="" +GITHUB_CLIENT_SECRET= + +GOOGLE_CLIENT_ID="" +GOOGLE_CLIENT_SECRET= + +LINKEDIN_CLIENT_ID="" +LINKEDIN_CLIENT_SECRET= + +MICROSOFT_CLIENT_ID="" +MICROSOFT_CLIENT_SECRET= + +REDDIT_CLIENT_ID="" +REDDIT_CLIENT_SECRET= + +SLACK_CLIENT_ID="" +SLACK_CLIENT_SECRET= + +SPOTIFY_CLIENT_ID="" +SPOTIFY_CLIENT_SECRET= + +TWITCH_CLIENT_ID="" +SPOTIFY_CLIENT_SECRET= + +X_CLIENT_ID="" +X_CLIENT_SECRET= + +ZOOM_CLIENT_ID="" +ZOOM_CLIENT_SECRET= +``` \ No newline at end of file diff --git a/app/en/home/deployment-hosting/evals-cicd/page.mdx b/app/en/home/deployment-hosting/evals-cicd/page.mdx index 7adf44558..9b7f9a658 100644 --- a/app/en/home/deployment-hosting/evals-cicd/page.mdx +++ b/app/en/home/deployment-hosting/evals-cicd/page.mdx @@ -1,3 +1,3 @@ # Set evals on CI/CD -Configure evaluations in your CI/CD pipeline. \ No newline at end of file +Coming soon. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/oauth-provider/page.mdx b/app/en/home/deployment-hosting/oauth-provider/page.mdx index f651e3000..77427ac50 100644 --- a/app/en/home/deployment-hosting/oauth-provider/page.mdx +++ b/app/en/home/deployment-hosting/oauth-provider/page.mdx @@ -1,3 +1,3 @@ # Configure an OAuth provider -Set up OAuth providers for your deployment. \ No newline at end of file +Coming soon. \ No newline at end of file diff --git a/app/en/home/deployment-hosting/on-premise-mcp/page.mdx b/app/en/home/deployment-hosting/on-premise-mcp/page.mdx index 21ada0d3a..9378f783f 100644 --- a/app/en/home/deployment-hosting/on-premise-mcp/page.mdx +++ b/app/en/home/deployment-hosting/on-premise-mcp/page.mdx @@ -1,3 +1,320 @@ -# Using On-premise MCP Servers +--- +title: "On-premises MCP Servers" +description: "Learn how to deploy MCP servers in a hybrid architecture" +--- -Guide for using on-premise MCP servers. \ No newline at end of file +import { Steps, Tabs, Callout } from "nextra/components"; + +# On-premise MCP Servers + + + + +An on-premises MCP server deployment allows you to execute tools in your own environment while still leveraging Arcade's cloud Engine infrastructure. This gives you the flexibility to access private resources, maintain data security, and customize your environment while leveraging Arcade's MCP server management and federation capabilities. + + + + + +- [Arcade account](https://api.arcade.dev/signup) +- [Arcade CLI](/home/quickstart) +- [uv package manager](https://docs.astral.sh/uv/getting-started/installation/) + + + + + +- How to run your MCP server with HTTP transport +- How to create a secure tunnel to expose it publicly +- How to register your server in Arcade +- How to test your server with the Arcade Playground + + + + +## How on-premises MCP servers work + +You can make your MCP server accessible to others by exposing it through a secure tunnel and registering it with Arcade. This allows remote users and services to interact with your tools without deploying to a cloud platform. + +The on-premises MCP server model uses a bidirectional connection between your local environment and Arcade's cloud engine: + +1. You run the Arcade MCP server in your environment (on-premises, private cloud, etc.) +2. Your MCP server is exposed to Arcade's cloud engine using a public URL +3. The Arcade cloud engine routes tool calls to your MCP server +4. Your MCP server processes the requests and returns responses to the engine + +## Benefits of on-premises MCP servers + +- **Resource access**: Access private databases, APIs, and other resources not accessible from Arcade's cloud +- **Data control**: Keep sensitive data within your environment while still using Arcade's capabilities +- **Custom environments**: Use specific dependencies or configurations required by your tools +- **Compliance**: Meet regulatory requirements by keeping data processing within your infrastructure + +## Setting up an on-premises MCP server + + + +### Setup your MCP Servers + +Follow the [Creating a MCP Server](/home/build-tools/create-a-mcp-server) guide to create your MCP Server. + +### Start your local MCP Server + +Ensure you are logged in to Arcade: + + + + +```bash +arcade login +``` + + + + +Add the environment variables to your shell: + +```bash +export ARCADE_API_KEY= +export ARCADE_USER_ID= +``` + +or to a `.env` file: + +```env filename=".env" +ARCADE_API_KEY= +ARCADE_USER_ID= +``` + + + + +Start your MCP server with HTTP transport: + +```bash +# Navigate to your entrypoint file +cd my_server/src/my_server + +# Run with HTTP transport (default) +uv run server.py +uv run server.py http +``` + +Your server will start on `http://localhost:8000`. Keep this terminal running. + +## Create a Secure Tunnel + +Open a **separate terminal** and create a tunnel using one of these options: + +- [ngrok](https://ngrok.com) is easy to set up and works across all platforms. +- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) provides persistent URLs and advanced features. +- [Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) is ideal for sharing within a team or organization. + + + + [ngrok](https://ngrok.com) is easy to set up and works across all platforms. + +1. **Install ngrok:** + + ```bash + # macOS + brew install ngrok + + # Or download from https://ngrok.com/download + ``` + +2. **Create a tunnel:** + + ```bash + ngrok http 8000 + ``` + +3. **Copy your URL:** + Look for the "Forwarding" line in the ngrok output: + + ``` + Forwarding https://abc123.ngrok-free.app -> http://localhost:8000 + ``` + + Copy the `https://abc123.ngrok-free.app` URL - this is your public URL. + +**Pros:** + +- Quick setup, no account required for basic use +- Automatic HTTPS +- Web dashboard to inspect requests + +**Cons:** + +- Free tier URLs change on each restart +- May show interstitial page for free tier + + + + + +[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/) provides persistent URLs and advanced features. + +1. **Install cloudflared:** + + ```bash + # macOS + brew install cloudflare/cloudflare/cloudflared + + # Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/ + ``` + +2. **Create a tunnel:** + + ```bash + cloudflared tunnel --url http://localhost:8000 + ``` + +3. **Copy your URL:** + Look for the "Your quick Tunnel has been created" message with your URL. + +**Pros:** + +- Free tier includes persistent URLs (with setup) +- Built-in DDoS protection +- Access control features + +**Cons:** + +- Requires Cloudflare account for persistent URLs +- More complex setup for advanced features + + + + + +[Tailscale Funnel](https://tailscale.com/kb/1223/tailscale-funnel) is ideal for sharing within a team or organization. + +1. **Install Tailscale:** + + ```bash + # macOS + brew install tailscale + + # Or download from https://tailscale.com/download + ``` + +2. **Authenticate:** + + ```bash + tailscale up + ``` + +3. **Create a funnel:** + + ```bash + tailscale funnel 8000 + ``` + +4. **Get your URL:** + Tailscale will display your funnel URL (e.g., `https://my-machine.tail-scale.ts.net`) + +**Pros:** + +- Persistent URLs tied to your machine +- Private by default (only shared with specified users) +- No bandwidth limits + +**Cons:** + +- Requires Tailscale account +- Best for team/organization use cases + + + + +### Register your MCP Server in Arcade + +Once you have a public URL, register your MCP server in the Arcade dashboard to make it accessible through the Arcade API. + +1. **Navigate to the MCP Servers page** in your [Arcade dashboard](https://api.arcade.dev/dashboard/servers) + +2. **Click "Add Server"** + +3. **Fill in the registration form:** + + - **ID**: Choose a unique identifier (e.g., `my-mcp-server`) + - **Server Type**: Select "Arcade" + - **URL**: Enter your public tunnel URL from Step 2 + - **Secret**: Enter a secret for your server (or use `dev` for testing) + - **Timeout**: Configure request timeout (default: 30s) + - **Retry**: Configure retry attempts (default: 3) + +4. **Click "Create"** + +Here's an example of a configuration: + +```yaml +ID: my-mcp-server +Server Type: Arcade +URL: https://abc123.ngrok-free.app +Secret: my-secure-secret-123 +Timeout: 30s +Retry: 3 +``` + +### Test the connection to your MCP Server + +You can now test your MCP Server by making requests using the Playground, or an MCP client: + + + + +1. **Go to the [Arcade Playground](https://api.arcade.dev/dashboard/playground/chat)** + +2. **Select your MCP server** from the dropdown + +3. **Choose a tool** from your server + +4. **Execute the tool** with test parameters + +5. **Verify the response:** + - Check that the response is correct + - View request logs in your local server terminal + - Inspect the tunnel dashboard for request details + + + + +1. Use an app that supports MCP clients, like AI assistants and IDEs: + - [Visual Studio Code](/home/mcp-clients/visual-studio-code) + - [Claude Desktop](/home/mcp-clients/claude-desktop) + - [Cursor](/home/mcp-clients/cursor) +1. Enable your MCP Server from the list of available MCP Servers +1. Verify that the response is correct and you see request logs in your MCP Server + + + + + + +## Key Concepts + +- **HTTP Transport** Run your server with HTTP transport to expose your tools via a REST/SSE API +- **Secure Tunnels** Create a secure tunnel to expose your server publicly +- **Arcade Registration** Register your server in Arcade to make it accessible through the Arcade API +- **Playground Testing** Test your server with the Arcade Playground + +## Best practices + +- **Persistent URLs**: For production use, set up a persistent public URL rather than ephemeral ones +- **TLS**: Use a TLS-enabled URL for production use +- **Monitoring**: Set up monitoring for your MCP Server to ensure availability + +## Troubleshooting + +- **Connection issues**: Ensure your public URL is accessible and that your local MCP Server is running +- **Timeout errors**: If your MCP Server takes too long to respond, increase the timeout value in the MCP Server configuration + +## Next steps + +- [Create custom tools](/home/build-tools/create-a-mcp-server) for your MCP Server +- [Set up authentication](/home/build-tools/create-a-tool-with-auth) for secure access to resources +- [Configure secrets](/home/build-tools/create-a-tool-with-secrets) for your MCP Server \ No newline at end of file diff --git a/app/en/home/deployment-hosting/overview/page.mdx b/app/en/home/deployment-hosting/overview/page.mdx index 5fbceff45..fce95e99a 100644 --- a/app/en/home/deployment-hosting/overview/page.mdx +++ b/app/en/home/deployment-hosting/overview/page.mdx @@ -1,3 +1,57 @@ -# Overview +--- +title: "Hosting Overview" +description: "Learn about the different ways to host Arcade" +--- -Overview of deployment and hosting options with Arcade. \ No newline at end of file +# Hosting Options + +The easiest and best way to use Arcade is via the Arcade Cloud service - sign up for free at [https://api.arcade.dev](https://api.arcade.dev). However, you might need to connect your tools to local resources (e.g. a local database or filesystem) or keep data within your own infrastructure. Don't worry, Arcade has you covered via either Arcade Cloud or our on-premise deployment options. + +## Arcade Cloud + +Arcade Cloud is the default option — sign up and start building immediately: + +- **Zero Infrastructure**: No servers or databases to manage +- **Automatic Updates**: Always access the latest tools and features +- **Built-in Scaling**: Handles traffic spikes automatically +- **Free Tier**: Start building without a credit card + +### MCP Server Deployment + +You can route and manage tool calls from your agents to MCP servers hosted anywhere—on your machine, on your own infrastructure, in a private cloud, or on Arcade Cloud. This allows you to mix the best public tools with your own private tools. + +Connect on-premises MCP servers to Arcade Cloud for a hybrid deployment: + +- **Private Resources**: Access databases and APIs within your network +- **Data Control**: Keep sensitive data in your environment +- **Custom Dependencies**: Use specific runtime requirements or configurations +- **Compliance**: Meet regulatory requirements while using Arcade's capabilities + +See [On-premise MCP Servers](/home/deployment/on-prem-mcp) for more information about how to use your own MCP servers running anywhere, and see [Arcade Deploy](/home/serve-tools/arcade-deploy) to learn how to deploy to Arcade Cloud. + +### Customizing Auth + +You don't have to self-host Arcade to customize your auth experiences. Arcade Cloud supports a number of auth providers out of the box, and you can provide your own OAuth app credentials to brand your end-user experience. We recommend doing this for all production use cases, so that you can have isolated rate limits with the OAuth service provider and you can give your users a consistent experience when they go through an auth flow. +You can still use the same tools when you customize your auth, no code changes are required. + +See [Customizing Auth](/home/auth-providers) for more information. + +### Arcade Cloud Pricing + +Arcade Cloud offers a generous free tier to get started: + +- **Free Tier**: Includes access to all public MCP Servers and basic features +- **Usage-Based**: Pay only for what you use as you scale + +Visit [https://api.arcade.dev](https://api.arcade.dev) for current pricing details. + +## On-Premise Deployments + +Fully on-premise deployments of the Arcade platform are available! Arcade can be deployed on Kubernetes via our Helm chart and Docker images as part of our enterprise offering. [Contact us to learn more](/home/contact-us). + +The requirements for deploying Arcade on-premise are: +* Kubernetes cluster (1.30+) (We have tested this helm chart on AKS, GKE, and EKS). +* Helm 3.x +* kubectl configured to access your cluster +* Cert Manager for securing Redis and Postgres and public ingress (see below) +* Nginx Ingress for accessing Arcade.dev from outside the cluster (see below) \ No newline at end of file diff --git a/app/en/home/google-adk/_meta.tsx b/app/en/home/google-adk/_meta.tsx deleted file mode 100644 index e0b5f430e..000000000 --- a/app/en/home/google-adk/_meta.tsx +++ /dev/null @@ -1,4 +0,0 @@ -export default { - "quickstart-python": "Quickstart (Python)", - "quickstart-typescript": "Quickstart (Typescript)", -}; diff --git a/app/en/home/google-adk/quickstart-python/page.mdx b/app/en/home/google-adk/quickstart-python/page.mdx deleted file mode 100644 index 5f28a1305..000000000 --- a/app/en/home/google-adk/quickstart-python/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Python) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using Google ADK with Python. \ No newline at end of file diff --git a/app/en/home/google-adk/quickstart-typescript/page.mdx b/app/en/home/google-adk/quickstart-typescript/page.mdx deleted file mode 100644 index 712d31c41..000000000 --- a/app/en/home/google-adk/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using Google ADK with TypeScript. \ No newline at end of file diff --git a/app/en/home/improve-performance/_meta.tsx b/app/en/home/improve-performance/_meta.tsx deleted file mode 100644 index 04730e0f9..000000000 --- a/app/en/home/improve-performance/_meta.tsx +++ /dev/null @@ -1,7 +0,0 @@ -export default { - "types-of-tools": "Types of tools", - "eval-starter-tools": "Write eval to assess combo of starter tools", - "custom-tool-improvements": - "Write custom tool that improves on relevant Starter tools", - "run-evaluations-2": "Run evaluations", -}; diff --git a/app/en/home/improve-performance/custom-tool-improvements/page.mdx b/app/en/home/improve-performance/custom-tool-improvements/page.mdx deleted file mode 100644 index 5ec9cca20..000000000 --- a/app/en/home/improve-performance/custom-tool-improvements/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# custom-tool-improvements - -Documentation coming soon. - -## Overview - -This section will contain detailed information about custom-tool-improvements. diff --git a/app/en/home/improve-performance/eval-starter-tools/page.mdx b/app/en/home/improve-performance/eval-starter-tools/page.mdx deleted file mode 100644 index 4df143348..000000000 --- a/app/en/home/improve-performance/eval-starter-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# eval-starter-tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about eval-starter-tools. diff --git a/app/en/home/improve-performance/run-evaluations-2/page.mdx b/app/en/home/improve-performance/run-evaluations-2/page.mdx deleted file mode 100644 index e3b7f1ae0..000000000 --- a/app/en/home/improve-performance/run-evaluations-2/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# run-evaluations-2 - -Documentation coming soon. - -## Overview - -This section will contain detailed information about run-evaluations-2. diff --git a/app/en/home/improve-performance/types-of-tools/page.mdx b/app/en/home/improve-performance/types-of-tools/page.mdx deleted file mode 100644 index f444c3598..000000000 --- a/app/en/home/improve-performance/types-of-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# types-of-tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about types-of-tools. diff --git a/app/en/home/langchain/_meta.tsx b/app/en/home/langchain/_meta.tsx deleted file mode 100644 index fb7cc7bbc..000000000 --- a/app/en/home/langchain/_meta.tsx +++ /dev/null @@ -1,5 +0,0 @@ -export default { - "quickstart-python": "Quickstart (Python)", - "quickstart-typescript": "Quickstart (Typescript)", - "using-langgraph-tools": "Using LangGraph tools", -}; diff --git a/app/en/home/langchain/quickstart-python/page.mdx b/app/en/home/langchain/quickstart-python/page.mdx deleted file mode 100644 index e3c23b656..000000000 --- a/app/en/home/langchain/quickstart-python/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Python) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using LangGraph with Python. \ No newline at end of file diff --git a/app/en/home/langchain/quickstart-typescript/page.mdx b/app/en/home/langchain/quickstart-typescript/page.mdx deleted file mode 100644 index 103d4694d..000000000 --- a/app/en/home/langchain/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using LangGraph with TypeScript. \ No newline at end of file diff --git a/app/en/home/langchain/using-langgraph-tools/page.mdx b/app/en/home/langchain/using-langgraph-tools/page.mdx deleted file mode 100644 index 0bdf9a500..000000000 --- a/app/en/home/langchain/using-langgraph-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Using LangGraph tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using LangGraph tools. \ No newline at end of file diff --git a/app/en/home/mastra/_meta.tsx b/app/en/home/mastra/_meta.tsx deleted file mode 100644 index 5df9193ec..000000000 --- a/app/en/home/mastra/_meta.tsx +++ /dev/null @@ -1,16 +0,0 @@ -import type { MetaRecord } from "nextra"; - -const meta: MetaRecord = { - "*": { - theme: { - breadcrumb: true, - toc: true, - copyPage: true, - }, - }, - "quickstart-typescript": { - title: "Quickstart (Typescript)", - }, -}; - -export default meta; diff --git a/app/en/home/mastra/quickstart-typescript/page.mdx b/app/en/home/mastra/quickstart-typescript/page.mdx deleted file mode 100644 index 4d05ea8f5..000000000 --- a/app/en/home/mastra/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using Mastra with TypeScript. \ No newline at end of file diff --git a/app/en/home/new-functionality/_meta.tsx b/app/en/home/new-functionality/_meta.tsx deleted file mode 100644 index d03a8c6b0..000000000 --- a/app/en/home/new-functionality/_meta.tsx +++ /dev/null @@ -1,5 +0,0 @@ -export default { - "eval-new-functionality": "Write eval for functionality you want", - "custom-toolkit": "Write custom toolkit", - "arcade-deploy-2": "Arcade Deploy", -}; diff --git a/app/en/home/new-functionality/arcade-deploy-2/page.mdx b/app/en/home/new-functionality/arcade-deploy-2/page.mdx deleted file mode 100644 index 984ef098c..000000000 --- a/app/en/home/new-functionality/arcade-deploy-2/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# arcade-deploy-2 - -Documentation coming soon. - -## Overview - -This section will contain detailed information about arcade-deploy-2. diff --git a/app/en/home/new-functionality/custom-toolkit/page.mdx b/app/en/home/new-functionality/custom-toolkit/page.mdx deleted file mode 100644 index 48d796c5a..000000000 --- a/app/en/home/new-functionality/custom-toolkit/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# custom-toolkit - -Documentation coming soon. - -## Overview - -This section will contain detailed information about custom-toolkit. diff --git a/app/en/home/new-functionality/eval-new-functionality/page.mdx b/app/en/home/new-functionality/eval-new-functionality/page.mdx deleted file mode 100644 index 7acdc5dcb..000000000 --- a/app/en/home/new-functionality/eval-new-functionality/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# eval-new-functionality - -Documentation coming soon. - -## Overview - -This section will contain detailed information about eval-new-functionality. diff --git a/app/en/home/newest-models/_meta.tsx b/app/en/home/newest-models/_meta.tsx deleted file mode 100644 index 0bc71b765..000000000 --- a/app/en/home/newest-models/_meta.tsx +++ /dev/null @@ -1,4 +0,0 @@ -export default { - "run-eval-new-model": "Run existing eval and observe outcome with new model", - "modify-tool-new-model": "Modify tool to work well with new model", -}; diff --git a/app/en/home/newest-models/modify-tool-new-model/page.mdx b/app/en/home/newest-models/modify-tool-new-model/page.mdx deleted file mode 100644 index 8cfa6e27f..000000000 --- a/app/en/home/newest-models/modify-tool-new-model/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# modify-tool-new-model - -Documentation coming soon. - -## Overview - -This section will contain detailed information about modify-tool-new-model. diff --git a/app/en/home/newest-models/run-eval-new-model/page.mdx b/app/en/home/newest-models/run-eval-new-model/page.mdx deleted file mode 100644 index b29b2853e..000000000 --- a/app/en/home/newest-models/run-eval-new-model/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# run-eval-new-model - -Documentation coming soon. - -## Overview - -This section will contain detailed information about run-eval-new-model. diff --git a/app/en/home/oai-agents/_meta.tsx b/app/en/home/oai-agents/_meta.tsx deleted file mode 100644 index e0b5f430e..000000000 --- a/app/en/home/oai-agents/_meta.tsx +++ /dev/null @@ -1,4 +0,0 @@ -export default { - "quickstart-python": "Quickstart (Python)", - "quickstart-typescript": "Quickstart (Typescript)", -}; diff --git a/app/en/home/oai-agents/quickstart-python/page.mdx b/app/en/home/oai-agents/quickstart-python/page.mdx deleted file mode 100644 index 2c7ba7b17..000000000 --- a/app/en/home/oai-agents/quickstart-python/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Python) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using OpenAI Agents with Python. \ No newline at end of file diff --git a/app/en/home/oai-agents/quickstart-typescript/page.mdx b/app/en/home/oai-agents/quickstart-typescript/page.mdx deleted file mode 100644 index 17a8cd8f1..000000000 --- a/app/en/home/oai-agents/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using OpenAI Agents with TypeScript. \ No newline at end of file diff --git a/app/en/home/open-agents/_meta.tsx b/app/en/home/open-agents/_meta.tsx deleted file mode 100644 index 27ad4a394..000000000 --- a/app/en/home/open-agents/_meta.tsx +++ /dev/null @@ -1,3 +0,0 @@ -export default { - "quickstart-python": "Quickstart (Python)", -}; diff --git a/app/en/home/open-agents/quickstart-python/page.mdx b/app/en/home/open-agents/quickstart-python/page.mdx deleted file mode 100644 index eb1d1c511..000000000 --- a/app/en/home/open-agents/quickstart-python/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Python) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using OpenAgents with Python. diff --git a/app/en/home/quickstarts/call-tool-easy/page.mdx b/app/en/home/quickstarts/call-tool-easy/page.mdx index 7def03e0c..b041167f0 100644 --- a/app/en/home/quickstarts/call-tool-easy/page.mdx +++ b/app/en/home/quickstarts/call-tool-easy/page.mdx @@ -1,7 +1,8 @@ -# Call a tool (easiest possible) +--- +title: "Call a tool in your agent" +description: "The simplest way to call an Arcade tool in your agent" +--- -The simplest way to call an Arcade tool. +# Call a tool in your agent -## Overview - -This is the easiest possible way to make your first tool call with Arcade. \ No newline at end of file +Coming soon! \ No newline at end of file diff --git a/app/en/home/quickstarts/call-tool-personal-agent/page.mdx b/app/en/home/quickstarts/call-tool-personal-agent/page.mdx index b2c9a8e26..fddd5f371 100644 --- a/app/en/home/quickstarts/call-tool-personal-agent/page.mdx +++ b/app/en/home/quickstarts/call-tool-personal-agent/page.mdx @@ -4,4 +4,22 @@ Learn how to integrate Arcade tools with your personal AI agent. ## Overview -This guide shows you how to call Arcade tools from your personal agent setup. \ No newline at end of file +Learn how to call tools in 3rd party agents, apps, or IDEs using the MCP Gateway. + +## Prerequisites + +- Arcade API key +- Supported MCP client + +## Setup Steps + +1. Configure your MCP Gateway +2. Connect to your client application +3. Test tool calling functionality + +## Supported Clients + +- Cursor +- Claude Desktop +- Visual Studio Code +- Other MCP-compatible applications \ No newline at end of file diff --git a/app/en/home/security-section/enterprise-sso/page.mdx b/app/en/home/security-section/enterprise-sso/page.mdx index c02c86065..009719dab 100644 --- a/app/en/home/security-section/enterprise-sso/page.mdx +++ b/app/en/home/security-section/enterprise-sso/page.mdx @@ -1,7 +1,8 @@ -# enterprise-sso +--- +title: "Enterprise Single Sign On" +description: "Learn about enterprise SSO integration" +--- -Documentation coming soon. +# Enterprise Single Sign On -## Overview - -This section will contain detailed information about enterprise-sso. +Coming soon! diff --git a/app/en/home/security-section/platform-security/page.mdx b/app/en/home/security-section/platform-security/page.mdx index b36cca51b..0a0971791 100644 --- a/app/en/home/security-section/platform-security/page.mdx +++ b/app/en/home/security-section/platform-security/page.mdx @@ -1,7 +1,8 @@ -# Platform Security - -Documentation coming soon. +--- +title: "Platform Security" +description: "Learn about Arcade platform security" +--- -## Overview +# Platform Security -This section will contain detailed information about platform-security. \ No newline at end of file +Coming soon! \ No newline at end of file diff --git a/app/en/home/security-section/rbac-config/page.mdx b/app/en/home/security-section/rbac-config/page.mdx index 8886db539..48c351e9b 100644 --- a/app/en/home/security-section/rbac-config/page.mdx +++ b/app/en/home/security-section/rbac-config/page.mdx @@ -1,7 +1,8 @@ -# rbac-config +--- +title: "Configuring Role Based Access Control for your organization" +description: "Learn how to configure RBAC for your organization" +--- -Documentation coming soon. +# Configuring Role Based Access Control for your organization -## Overview - -This section will contain detailed information about rbac-config. +Coming soon! diff --git a/app/en/home/setup/api-key/page.mdx b/app/en/home/setup/api-key/page.mdx index 6d342401b..b1c436f3e 100644 --- a/app/en/home/setup/api-key/page.mdx +++ b/app/en/home/setup/api-key/page.mdx @@ -1,7 +1,108 @@ -# API Key +--- +title: "Getting Your API Key" +description: "Learn how to obtain and manage your Arcade API key" +--- -Learn how to obtain and configure your API key for Arcade. +import { Steps, Tabs, Callout } from "nextra/components"; +import { SignupLink } from "@/app/_components/analytics"; -## Overview +# Getting Your API Key -This guide covers setting up your API key to start using Arcade services. \ No newline at end of file +Before you begin, you'll need an Arcade account - if you haven't created one yet, you can sign up here. Once you have an account, you can generate API keys through either our dashboard or CLI. + + + + + +### Using the Dashboard + +
+ +
+ + +### Navigate to API Keys page +Visit the [API Keys page](https://api.arcade.dev/dashboard/api-keys) in Arcade Dashboard. + +### Create a new API key + +1. Click the `Create API Key` button in the top right +2. Enter a descriptive name to help identify your key +3. Click `Create API Key` to generate your key + +### Save your API key securely + +1. Copy your API key immediately - it will only be shown once +2. Store it securely +3. You can always generate new keys if needed + + + + + + + +### Using the CLI + + + +### Install and login + +1. Install the Arcade CLI: + + + + +```bash +uv tool install arcade-mcp +``` + + +This will install the Arcade CLI as a [uv tool](https://docs.astral.sh/uv/guides/tools/), making it available system wide. + + + + +```bash +pip install arcade-mcp +``` + + + +2. Start the login process: + +```bash +arcade login +``` + +### Complete setup + +The CLI will automatically: + +- Print your API key to the console +- Save your credentials to `~/.arcade/credentials.yaml` + + + + + + + + API keys are administrator credentials. Anyone who has your API key can make + requests to Arcade as you. Always store your API keys in a safe place, such as + system environment variables, and never commit them to version control, share + them publicly, or use them in browser or frontend code. + +## Next Steps + +Once you have your API key, you can: + +- [Start using tools](/home/quickstart) +- [Create custom tools](/home/build-tools/create-a-mcp-server) \ No newline at end of file diff --git a/app/en/home/setup/connect-arcade-docs/page.mdx b/app/en/home/setup/connect-arcade-docs/page.mdx index 5ca76eeec..d575d5d7c 100644 --- a/app/en/home/setup/connect-arcade-docs/page.mdx +++ b/app/en/home/setup/connect-arcade-docs/page.mdx @@ -1,7 +1,26 @@ -# Connect Arcade Docs to Your IDE +--- +title: "Agentic Development" +description: "Learn how to speed up your development with agents in your IDEs" +--- -Set up Arcade documentation integration with your development environment. +# Agentic Development -## Overview +Give your AI IDE access to Arcade.dev's documentation using our [llms.txt](/llms.txt) file, or use [context7](https://context7.com/arcadeai/docs). This allows Claude Code, Cursor, and other AI IDEs to access the documentation and help you write code. -This guide shows you how to connect Arcade documentation directly to your IDE for seamless development. \ No newline at end of file +## LLMs.txt + +LLMs.txt is a file format that allows you to give your AI IDE access to Arcade.dev's documentation in a format that can be easily parsed by the LLM. All you need to do is paste in the content of the file into your IDE's settings, or reference the docs, e.g. via [Cursor's `@docs` annotation](https://cursor.com/docs/context/symbols#docs). + +Our LLMs.txt files are available at [`/llms.txt`](/llms.txt). + +![LLMs.txt example](/images/agentic-development/cursor-llms-txt.png) + +Learn more about the LLMs.txt file format [here](https://llmstxt.org/). + +## Context7 + +Context7 is an MCP server designed to provide Large Language Models (LLMs) and AI code editors with up-to-date, version-specific documentation and code examples. It helps prevent AI models from "hallucinating" or providing outdated code by fetching accurate information directly from its knowledge base and injecting it into the LLM's prompt, ensuring more reliable and accurate coding assistance + +To use Context7, you first need to add the [Context7 MCP server](https://github.com/upstash/context7) to your editor, and then select the [`arcadeai/docs` project](https://context7.com/arcadeai/docs). + +Learn more about Context7 [here](https://context7.com/). \ No newline at end of file diff --git a/app/en/home/sharing-with-end-users/custom-auth/dropbox/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/dropbox/page.mdx new file mode 100644 index 000000000..302d308a5 --- /dev/null +++ b/app/en/home/sharing-with-end-users/custom-auth/dropbox/page.mdx @@ -0,0 +1,185 @@ +import { Tabs, Callout, Steps } from "nextra/components"; + +# Dropbox + + + At this time, Arcade does not offer a default Dropbox Auth Provider. To use + Dropbox auth, you must create a custom Auth Provider with your own Dropbox + OAuth 2.0 credentials as described below. + + +The Dropbox auth provider enables tools and agents to call the Dropbox API on behalf of a user. + +### What's documented here + +This page describes how to use and configure Dropbox auth with Arcade. + +This auth provider is used by: + +- Your [app code](#using-dropbox-auth-in-app-code) that needs to call Dropbox APIs +- Or, your [custom tools](#using-dropbox-auth-in-custom-tools) that need to call Dropbox APIs + +## Configuring Dropbox auth + + + When using your own app credentials, make sure you configure your project to + use a [custom user + verifier](/home/auth/secure-auth-production#build-a-custom-user-verifier). + Without this, your end-users will not be able to use your app or agent in + production. + + +In a production environment, you will most likely want to use your own Dropbox app credentials. This way, your users will see your application's name requesting permission. + + +Before showing how to configure your Dropbox app credentials, let's go through the steps to create a Dropbox app. + +### Create a Dropbox app + +- Create a Dropbox Application in the [Dropbox App Console](https://www.dropbox.com/developers/apps) +- In the Settings tab, under the "OAuth 2" section, set the redirect URI to the redirect URL generated by Arcade (see below) +- In the Permissions tab, add any scopes that your app will need +- In the Settings tab, copy the App key (Client ID) and App secret (Client Secret), which you'll need below + +Next, add the Dropbox app to Arcade. + +## Configuring your own Dropbox Auth Provider in Arcade + + + + +### Configure Dropbox Auth Using the Arcade Dashboard GUI + + + +#### Access the Arcade Dashboard + +To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment. + +#### Navigate to the OAuth Providers page + +- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**. +- Click **Add OAuth Provider** in the top right corner. +- Select the **Included Providers** tab at the top. +- In the **Provider** dropdown, select **Dropbox**. + +#### Enter the provider details + +- Choose a unique **ID** for your provider (e.g. "my-dropbox-provider"). +- Optionally enter a **Description**. +- Enter the **Client ID** and **Client Secret** from your Dropbox app. +- Note the **Redirect URL** generated by Arcade. This must be added to your Dropbox app's Redirect URIs. + +#### Create the provider + +Hit the **Create** button and the provider will be ready to be used. + + + +When you use tools that require Dropbox auth using your Arcade account credentials, Arcade will automatically use this Dropbox OAuth provider. If you have multiple Dropbox providers, see [using multiple auth providers of the same type](/home/auth-providers#using-multiple-providers-of-the-same-type) for more information. + + + + +## Using Dropbox auth in app code + +Use the Dropbox auth provider in your own agents and AI apps to get a user-scoped token for the Dropbox API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works. + +Use `client.auth.start()` to get a user token for the Dropbox API: + + + + +```python {8-12} +from arcadepy import Arcade + +client = Arcade() # Automatically finds the `ARCADE_API_KEY` env variable + +user_id = "{arcade_user_id}" + +# Start the authorization process +auth_response = client.auth.start( + user_id=user_id, + provider="dropbox", + scopes=["openid", "sharing.read", "files.metadata.read"], +) + +if auth_response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(auth_response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(auth_response) + +token = auth_response.context.token +# Do something interesting with the token... +``` + + + + + +```javascript {8-10} +import { Arcade } from "@arcadeai/arcadejs"; + +const client = new Arcade(); + +const userId = "{arcade_user_id}"; + +// Start the authorization process +const authResponse = await client.auth.start(userId, "dropbox", { + scopes: ["openid", "sharing.read", "files.metadata.read"], +}); + +if (authResponse.status !== "completed") { + console.log("Please complete the authorization challenge in your browser:"); + console.log(authResponse.url); +} + +// Wait for the authorization to complete +authResponse = await client.auth.waitForCompletion(authResponse); + +const token = authResponse.context.token; +// Do something interesting with the token... +``` + + + + + +## Using Dropbox auth in custom tools + +You can author your own [custom tools](/home/build-tools/create-a-mcp-server) that interact with the Dropbox API. + +Use the `Dropbox()` auth class to specify that a tool requires authorization with Dropbox. The `context.authorization.token` field will be automatically populated with the user's Dropbox token: + +```python {5-6,9-13,23} +from typing import Annotated, Optional + +import httpx + +from arcade_tdk import ToolContext, tool +from arcade_tdk.auth import Dropbox + + +@tool( + requires_auth=Dropbox( + scopes=["files.metadata.read"], + ) +) +async def list_files( + context: ToolContext, + path: Annotated[ + Optional[str], + "The path to the folder to list the contents of. Defaults to empty string to list the root folder.", + ] = "", +) -> Annotated[dict, "List of servers the user is a member of"]: + """Starts returning the contents of a folder.""" + url = "https://api.dropboxapi.com/2/files/list_folder" + headers = {"Authorization": f"Bearer {context.authorization.token}"} + + async with httpx.AsyncClient() as client: + response = await client.post(url, headers=headers, json={"path": path}) + response.raise_for_status() + return response.json() +``` \ No newline at end of file diff --git a/app/en/home/sharing-with-end-users/custom-auth/overview/page.mdx b/app/en/home/sharing-with-end-users/custom-auth/overview/page.mdx index fd934d20e..7876d1e01 100644 --- a/app/en/home/sharing-with-end-users/custom-auth/overview/page.mdx +++ b/app/en/home/sharing-with-end-users/custom-auth/overview/page.mdx @@ -1,3 +1,182 @@ -# Overview +--- +title: Auth Providers +description: Registry of all auth providers available in the Arcade ecosystem +--- -Learn about customizing authentication for your app. \ No newline at end of file +# Auth Providers + +import { ToolCard } from "@/app/_components/tool-card"; + +Auth providers enable users to seamlessly and securely allow Arcade tools to access their data. + +Arcade has several auth providers available in the Arcade Cloud Platform so you don't have to configure your own. However, using Arcade's auth providers means that your users will see the Arcade brand (name and logo) on the auth screen and your authentications will share any rate limits from those providers with other Arcade customers. + +It can be useful to configure your own auth provider for the following reasons: + +- You want to use your own brand on the auth screen +- You want to isolate your rate limits from other Arcade customers +- You want to use a service that Arcade [does not have a built-in auth provider for](/home/auth-providers/oauth2) + +After adding an auth provider used by an Arcade tool, executing the tool will automatically use your auth provider. Even in the Arcade Cloud Platform, your auth provider will take precedence over the arcade-provided auth provider. + +Adding multiple providers of the same type, not including the arcade-provided ones, can cause Arcade's tool authorization to fail, see [Using multiple providers of the same type](#using-multiple-providers-of-the-same-type) for more information. + +## Catalog of providers + +For more information on how to customize your auth provider, select an auth provider from the list below: + +
+ +
+ + + + + + + + + + + + + + + + + + +
+ +If the auth provider you need is not listed, try the [OAuth 2.0](/home/auth-providers/oauth2) provider, or [get in touch](mailto:contact@arcade.dev) with us! + +## Using multiple providers of the same type + +You can create multiple auth providers of the same type, for example, you can have multiple Google auth providers, each with their own client ID and secret. This might be useful if you want separate Google clients to handle calendar and email scopes, for example. + +However, Arcade's tools are configured to select an auth provider by the type. This means that if you have multiple auth providers of the same type, Arcade will not know which one to use and authorizing the tool will fail. + +To work around this, you can fork Arcade's tools and modify them to specify your own auth provider by the unique ID that you give each of them. For example, if you have two Google auth providers, `acme-google-calendar` and `acme-google-email`, you can modify Arcade's Gmail.ListEmails tool like this: + +```python +@tool( + requires_auth=Google( + id="acme-google-email", # This is the unique ID you gave your auth provider + scopes=["https://www.googleapis.com/auth/gmail.readonly"], + ) +) +async def list_emails( +# ... +``` + +This is similar to the pattern used in the generic OAuth2 provider, but instead of using the `OAuth2` class, you use the `Google` class and specify the `id` of the auth provider you want to use. + +See the docs about [Authoring Tools](/home/build-tools/create-a-mcp-server) for more information on how to create and serve a MCP Server. \ No newline at end of file diff --git a/app/en/home/sharing-with-end-users/multi-user-auth/page.mdx b/app/en/home/sharing-with-end-users/multi-user-auth/page.mdx index 6b55c7ec7..4895d75a9 100644 --- a/app/en/home/sharing-with-end-users/multi-user-auth/page.mdx +++ b/app/en/home/sharing-with-end-users/multi-user-auth/page.mdx @@ -1,7 +1,8 @@ -# multi user auth +--- +title: "Set-up secure multi-user auth for your app" +description: "Learn how to set up secure multi-user authentication for your application" +--- -Documentation for multi user auth. +# Set-up secure multi-user auth for your app -## Overview - -Content for this section coming soon. +Coming soon! diff --git a/app/en/home/tool-writing-basics/_meta.tsx b/app/en/home/tool-writing-basics/_meta.tsx deleted file mode 100644 index 562b48c83..000000000 --- a/app/en/home/tool-writing-basics/_meta.tsx +++ /dev/null @@ -1,9 +0,0 @@ -export default { - "when-build-tools": "When to build tools", - "compare-server-types": "Compare Server Types", - "create-tool-auth": "Create a tool with auth", - "create-tool-secrets": "Create a tool with secrets", - "runtime-data-access": "Accessing runtime data", - "call-tools-mcp": "Call tools from MCP clients", - "run-evaluations": "Run evaluations", -}; diff --git a/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx b/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx deleted file mode 100644 index d5ecbbf58..000000000 --- a/app/en/home/tool-writing-basics/call-tools-mcp/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# call-tools-mcp - -Documentation coming soon. - -## Overview - -This section will contain detailed information about call-tools-mcp. diff --git a/app/en/home/tool-writing-basics/compare-server-types/page.mdx b/app/en/home/tool-writing-basics/compare-server-types/page.mdx deleted file mode 100644 index 580e3b3c1..000000000 --- a/app/en/home/tool-writing-basics/compare-server-types/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# compare-server-types - -Documentation coming soon. - -## Overview - -This section will contain detailed information about compare-server-types. diff --git a/app/en/home/tool-writing-basics/create-tool-auth/page.mdx b/app/en/home/tool-writing-basics/create-tool-auth/page.mdx deleted file mode 100644 index 412fb1902..000000000 --- a/app/en/home/tool-writing-basics/create-tool-auth/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# create-tool-auth - -Documentation coming soon. - -## Overview - -This section will contain detailed information about create-tool-auth. diff --git a/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx b/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx deleted file mode 100644 index 27de627a4..000000000 --- a/app/en/home/tool-writing-basics/create-tool-secrets/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# create-tool-secrets - -Documentation coming soon. - -## Overview - -This section will contain detailed information about create-tool-secrets. diff --git a/app/en/home/tool-writing-basics/run-evaluations/page.mdx b/app/en/home/tool-writing-basics/run-evaluations/page.mdx deleted file mode 100644 index ef0cdc212..000000000 --- a/app/en/home/tool-writing-basics/run-evaluations/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# run-evaluations - -Documentation coming soon. - -## Overview - -This section will contain detailed information about run-evaluations. diff --git a/app/en/home/tool-writing-basics/runtime-data-access/page.mdx b/app/en/home/tool-writing-basics/runtime-data-access/page.mdx deleted file mode 100644 index f35802fec..000000000 --- a/app/en/home/tool-writing-basics/runtime-data-access/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# runtime-data-access - -Documentation coming soon. - -## Overview - -This section will contain detailed information about runtime-data-access. diff --git a/app/en/home/tool-writing-basics/when-build-tools/page.mdx b/app/en/home/tool-writing-basics/when-build-tools/page.mdx deleted file mode 100644 index 462900ed0..000000000 --- a/app/en/home/tool-writing-basics/when-build-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# when-build-tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about when-build-tools. diff --git a/app/en/home/tool-writing-reference/_meta.tsx b/app/en/home/tool-writing-reference/_meta.tsx deleted file mode 100644 index 681c0146e..000000000 --- a/app/en/home/tool-writing-reference/_meta.tsx +++ /dev/null @@ -1,7 +0,0 @@ -export default { - "organize-mcp-tools": "Organize MCP server tools", - "useful-tool-errors": "Providing useful tool errors", - "retry-tools": "Retry tools with improved prompt", - "migrate-toolkits": "Migrate from toolkits to MCP Servers", - "why-evaluate": "Why evaluate tools?", -}; diff --git a/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx b/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx deleted file mode 100644 index e53ec9998..000000000 --- a/app/en/home/tool-writing-reference/migrate-toolkits/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# migrate-toolkits - -Documentation coming soon. - -## Overview - -This section will contain detailed information about migrate-toolkits. diff --git a/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx b/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx deleted file mode 100644 index 02a6fbf44..000000000 --- a/app/en/home/tool-writing-reference/organize-mcp-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# organize-mcp-tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about organize-mcp-tools. diff --git a/app/en/home/tool-writing-reference/retry-tools/page.mdx b/app/en/home/tool-writing-reference/retry-tools/page.mdx deleted file mode 100644 index 081f1c136..000000000 --- a/app/en/home/tool-writing-reference/retry-tools/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# retry-tools - -Documentation coming soon. - -## Overview - -This section will contain detailed information about retry-tools. diff --git a/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx b/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx deleted file mode 100644 index c250ee99a..000000000 --- a/app/en/home/tool-writing-reference/useful-tool-errors/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# useful-tool-errors - -Documentation coming soon. - -## Overview - -This section will contain detailed information about useful-tool-errors. diff --git a/app/en/home/tool-writing-reference/why-evaluate/page.mdx b/app/en/home/tool-writing-reference/why-evaluate/page.mdx deleted file mode 100644 index da0906e4e..000000000 --- a/app/en/home/tool-writing-reference/why-evaluate/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# why-evaluate - -Documentation coming soon. - -## Overview - -This section will contain detailed information about why-evaluate. diff --git a/app/en/home/triggers-section/_meta.tsx b/app/en/home/triggers-section/_meta.tsx deleted file mode 100644 index 25016d02f..000000000 --- a/app/en/home/triggers-section/_meta.tsx +++ /dev/null @@ -1,5 +0,0 @@ -export default { - "background-agents": "Set up a background agent using events", - "scheduled-executions": "Set up scheduled tool executions", - "direct-api-call": "Direct Third-Party API Call", -}; diff --git a/app/en/home/triggers-section/background-agents/page.mdx b/app/en/home/triggers-section/background-agents/page.mdx deleted file mode 100644 index dee52007f..000000000 --- a/app/en/home/triggers-section/background-agents/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# background-agents - -Documentation coming soon. - -## Overview - -This section will contain detailed information about background-agents. diff --git a/app/en/home/triggers-section/direct-api-call/page.mdx b/app/en/home/triggers-section/direct-api-call/page.mdx deleted file mode 100644 index 7f370bd51..000000000 --- a/app/en/home/triggers-section/direct-api-call/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# direct-api-call - -Documentation coming soon. - -## Overview - -This section will contain detailed information about direct-api-call. diff --git a/app/en/home/triggers-section/scheduled-executions/page.mdx b/app/en/home/triggers-section/scheduled-executions/page.mdx deleted file mode 100644 index c6116c323..000000000 --- a/app/en/home/triggers-section/scheduled-executions/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# scheduled-executions - -Documentation coming soon. - -## Overview - -This section will contain detailed information about scheduled-executions. diff --git a/app/en/home/vercelai/_meta.tsx b/app/en/home/vercelai/_meta.tsx deleted file mode 100644 index c1d2a14cd..000000000 --- a/app/en/home/vercelai/_meta.tsx +++ /dev/null @@ -1,3 +0,0 @@ -export default { - "quickstart-typescript": "Quickstart (Typescript)", -}; diff --git a/app/en/home/vercelai/quickstart-typescript/page.mdx b/app/en/home/vercelai/quickstart-typescript/page.mdx deleted file mode 100644 index 41312ce5a..000000000 --- a/app/en/home/vercelai/quickstart-typescript/page.mdx +++ /dev/null @@ -1,7 +0,0 @@ -# Quickstart (Typescript) - -Documentation coming soon. - -## Overview - -This section will contain detailed information about using Vercel AI with TypeScript. \ No newline at end of file diff --git a/app/en/home/what-is-agent/intro-to-tag/page.mdx b/app/en/home/what-is-agent/intro-to-tag/page.mdx index 8ca542a27..2229639cf 100644 --- a/app/en/home/what-is-agent/intro-to-tag/page.mdx +++ b/app/en/home/what-is-agent/intro-to-tag/page.mdx @@ -1,3 +1,3 @@ # Intro to TAG -Introduction to Tool-Augmented Generation (TAG). \ No newline at end of file +Coming soon. \ No newline at end of file diff --git a/app/en/home/what-is-agent/why-agents-call-tools/page.mdx b/app/en/home/what-is-agent/why-agents-call-tools/page.mdx index 1d9a714f7..40df4c774 100644 --- a/app/en/home/what-is-agent/why-agents-call-tools/page.mdx +++ b/app/en/home/what-is-agent/why-agents-call-tools/page.mdx @@ -1,3 +1,3 @@ # Why and how do agents call tools? -Understanding why agents need tools and how they use them. \ No newline at end of file +Coming soon. \ No newline at end of file From 5dfa91681d122e17d32d8a20921394568715bd0d Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 12:39:29 -0800 Subject: [PATCH 06/11] Consolidate example agents into single page under Getting Started MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Convert "Example agents" section from separate pages to single unified page - Move example agents from standalone section to under "Getting Started" - Combine confluence-jira-example and daily-digest-example into one page - Remove old individual example agent directories and pages - Update sidebar navigation to show "Example Agents" as single link 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- app/en/home/_meta.tsx | 9 +-------- app/en/home/confluence-jira-example/page.mdx | 3 --- app/en/home/daily-digest-example/page.mdx | 3 --- app/en/home/example-agents/page.mdx | 11 +++++++++++ 4 files changed, 12 insertions(+), 14 deletions(-) delete mode 100644 app/en/home/confluence-jira-example/page.mdx delete mode 100644 app/en/home/daily-digest-example/page.mdx create mode 100644 app/en/home/example-agents/page.mdx diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index 9fc61b6f7..b21aa934b 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -34,16 +34,9 @@ export const meta: MetaRecord = { setup: "Setup", quickstarts: "Quickstarts", "common-use-cases": "Common Use Cases", + "example-agents": "Example Agents", glossary: "Glossary", faq: "FAQ", - "-- Example agents": { - type: "separator", - title: "Example agents", - }, - "confluence-jira-example": - "Turn Confluence into Jira Tickets/Turn Google doc into Linear Tickets", - "daily-digest-example": - "Daily Digest: Summarize your Google Calendar / Email stuffs", "-- Guides": { type: "separator", title: "Guides", diff --git a/app/en/home/confluence-jira-example/page.mdx b/app/en/home/confluence-jira-example/page.mdx deleted file mode 100644 index 360daf8d0..000000000 --- a/app/en/home/confluence-jira-example/page.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Turn Confluence into Jira Tickets/Turn Google doc into Linear Tickets - -Example agent that converts Confluence pages into Jira tickets or Google docs into Linear tickets. \ No newline at end of file diff --git a/app/en/home/daily-digest-example/page.mdx b/app/en/home/daily-digest-example/page.mdx deleted file mode 100644 index f7c9ff52a..000000000 --- a/app/en/home/daily-digest-example/page.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Daily Digest: Summarize your Google Calendar / Email stuffs - -Example agent that creates daily digests from your Google Calendar and email. \ No newline at end of file diff --git a/app/en/home/example-agents/page.mdx b/app/en/home/example-agents/page.mdx new file mode 100644 index 000000000..5d7988312 --- /dev/null +++ b/app/en/home/example-agents/page.mdx @@ -0,0 +1,11 @@ +# Example Agents + +Explore these example agents to see what's possible with Arcade. + +## Turn Confluence into Jira Tickets / Google Docs into Linear Tickets + +Example agent that converts Confluence pages into Jira tickets or Google docs into Linear tickets. + +## Daily Digest: Summarize your Google Calendar / Email + +Example agent that creates daily digests from your Google Calendar and email. \ No newline at end of file From 680cc4c4e2d4663c0a930c8f8e96ee644f187b85 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 12:52:17 -0800 Subject: [PATCH 07/11] Normalize page titles and sidebar items to match new IA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update section and page titles throughout the navigation to be more consistent: Main section changes: - "Calling tools" → "Call tools" - "Creating tools" → "Create tools" - "Sharing your agent with end-users" → "Share your agent with end-users" - "APIs & SDKs" → "APIs" Subsection updates: - "Tool building basics" → "Build a tool" - "Evaluating tools" → "Evaluate tools" - "Building tools to get more performance..." → "Improve an existing toolkit" - "Error Handling"/"Error handling" → "Handle errors" - "Triggers" → "Trigger tool calls" - "Customizing Auth" → "Customize auth" Page title normalization: - Remove "-ing" suffixes for consistency (Connecting → Connect) - Use imperative mood throughout (Set up, Configure, etc.) - Add Java Client page placeholder 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- app/en/home/_meta.tsx | 10 +++++----- app/en/home/arcade-clients/_meta.tsx | 1 + .../home/arcade-clients/java-client/page.mdx | 3 +++ app/en/home/calling-tools/_meta.tsx | 20 +++++++++---------- .../home/configure-arcade-section/_meta.tsx | 2 +- app/en/home/creating-tools/_meta.tsx | 11 +++++----- app/en/home/deployment-hosting/_meta.tsx | 4 ++-- app/en/home/security-section/_meta.tsx | 2 +- app/en/home/sharing-with-end-users/_meta.tsx | 4 ++-- 9 files changed, 30 insertions(+), 27 deletions(-) create mode 100644 app/en/home/arcade-clients/java-client/page.mdx diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index b21aa934b..d57e1aea4 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -42,10 +42,10 @@ export const meta: MetaRecord = { title: "Guides", }, "configure-arcade-section": "Configure Arcade", - "calling-tools": "Calling tools", - "creating-tools": "Creating tools", + "calling-tools": "Call tools", + "creating-tools": "Create tools", "agent-frameworks": "Agent Frameworks", - "sharing-with-end-users": "Sharing your agent with end-users", + "sharing-with-end-users": "Share your agent with end-users", "observability-platforms": "Observability Platforms", "deployment-hosting": "Deployment and Hosting", "security-section": "Security and Compliance", @@ -69,9 +69,9 @@ export const meta: MetaRecord = { title: "Blog", href: "https://blog.arcade.dev", }, - "-- APIs & SDKs": { + "-- APIs": { type: "separator", - title: "APIs & SDKs", + title: "APIs", }, api: "API", "arcade-mcp": "Arcade MCP (MCP Server SDK)", diff --git a/app/en/home/arcade-clients/_meta.tsx b/app/en/home/arcade-clients/_meta.tsx index 8afb6e990..a7403d26d 100644 --- a/app/en/home/arcade-clients/_meta.tsx +++ b/app/en/home/arcade-clients/_meta.tsx @@ -2,4 +2,5 @@ export default { "python-client": "Python Client", "javascript-typescript-client": "JavaScript / TypeScript Client", "go-client": "Go Client", + "java-client": "Java Client", }; diff --git a/app/en/home/arcade-clients/java-client/page.mdx b/app/en/home/arcade-clients/java-client/page.mdx new file mode 100644 index 000000000..79548c9b6 --- /dev/null +++ b/app/en/home/arcade-clients/java-client/page.mdx @@ -0,0 +1,3 @@ +# Java Client + +Coming soon. \ No newline at end of file diff --git a/app/en/home/calling-tools/_meta.tsx b/app/en/home/calling-tools/_meta.tsx index 90a46405b..ab428b8ec 100644 --- a/app/en/home/calling-tools/_meta.tsx +++ b/app/en/home/calling-tools/_meta.tsx @@ -1,27 +1,27 @@ export default { overview: "Overview", - "error-handling": "Error Handling", + "error-handling": "Handle errors", "-- In 3rd party applications": { type: "separator", title: "In 3rd party applications", }, "third-party-apps": "Call a tool in your IDEs, MCP clients, or agents", - "mcp-clients": "Connecting to a MCP Client", - "evaluation-suite": "Creating an evaluation suite to test tools", - "mcp-gateway-auth": "Adding authentication to your MCP Gateway", + "mcp-clients": "Connect to a MCP client", + "evaluation-suite": "Create an evaluation suite to test tools", + "mcp-gateway-auth": "Add authentication to your MCP Gateway", "-- In custom applications": { type: "separator", title: "In custom applications", }, - "calling-tools-custom-apps": "Calling tools in your custom apps", - "authorized-tool-calling": "Authorized Tool Calling", - "auth-status-check": "Checking Authorization Status", + "calling-tools-custom-apps": "Call tools in your custom apps", + "authorized-tool-calling": "Authorize tool calls", + "auth-status-check": "Check authorization status", "tool-formats": "Tool formats", - "connect-arcade-llm": "Connecting Arcade tools to your LLM", + "connect-arcade-llm": "Connect Arcade tools to your LLM", "ensure-consistent-evals": "Ensure consistent tool calls with evals", - "-- Triggers": { + "-- Trigger tool calls": { type: "separator", - title: "Triggers", + title: "Trigger tool calls", }, "background-agents": "Set up a background agent using events", "scheduled-executions": "Set up scheduled tool executions", diff --git a/app/en/home/configure-arcade-section/_meta.tsx b/app/en/home/configure-arcade-section/_meta.tsx index 23640a9ad..4c77d9e62 100644 --- a/app/en/home/configure-arcade-section/_meta.tsx +++ b/app/en/home/configure-arcade-section/_meta.tsx @@ -2,5 +2,5 @@ export default { "dashboard-section": "Dashboard", "create-tenants-section": "Create Organization", "create-projects-section": "Create Projects", - "arcade-cli-section": "Using Arcade's CLI", + "arcade-cli-section": "Use Arcade's CLI", }; diff --git a/app/en/home/creating-tools/_meta.tsx b/app/en/home/creating-tools/_meta.tsx index f096b94d6..f2d9f53ae 100644 --- a/app/en/home/creating-tools/_meta.tsx +++ b/app/en/home/creating-tools/_meta.tsx @@ -1,11 +1,10 @@ export default { - "tool-basics": "Tool building basics", - "evaluating-tools": "Evaluating tools", - "performance-tools": - "Building tools to get more performance out of existing toolkits", + "tool-basics": "Build a tool", + "evaluating-tools": "Evaluate tools", + "performance-tools": "Improve an existing toolkit", "new-functionality": - "Building tools with agent functionality that doesn't exist", + "Build tools with agent functionality that doesn't exist", "newest-models": "Ensure tools work with the newest models", - "error-handling": "Error handling", + "error-handling": "Handle errors", "registry-early-access": "Registry Early Access", }; diff --git a/app/en/home/deployment-hosting/_meta.tsx b/app/en/home/deployment-hosting/_meta.tsx index f7fe2ebae..72d27676a 100644 --- a/app/en/home/deployment-hosting/_meta.tsx +++ b/app/en/home/deployment-hosting/_meta.tsx @@ -1,7 +1,7 @@ export default { overview: "Overview", - "cloud-infrastructure": "Using Arcade's Cloud Infrastructure", - "on-premise-mcp": "Using On-premise MCP Servers", + "cloud-infrastructure": "Use Arcade's Cloud Infrastructure", + "on-premise-mcp": "Use on-premise MCP Servers", "configure-engine": "Configure Arcade's Engine", "oauth-provider": "Configure an OAuth provider", "evals-cicd": "Set evals on CI/CD", diff --git a/app/en/home/security-section/_meta.tsx b/app/en/home/security-section/_meta.tsx index ec6d02747..fb98eb1e1 100644 --- a/app/en/home/security-section/_meta.tsx +++ b/app/en/home/security-section/_meta.tsx @@ -1,5 +1,5 @@ export default { "platform-security": "Platform Security", "enterprise-sso": "Enterprise Single Sign On", - "rbac-config": "Configuring Role Based Access Control for your organization", + "rbac-config": "Configure role-based access control for your organization", }; diff --git a/app/en/home/sharing-with-end-users/_meta.tsx b/app/en/home/sharing-with-end-users/_meta.tsx index 4d1259dce..a5b904275 100644 --- a/app/en/home/sharing-with-end-users/_meta.tsx +++ b/app/en/home/sharing-with-end-users/_meta.tsx @@ -1,4 +1,4 @@ export default { - "multi-user-auth": "Set-up secure multi-user auth for your app", - "custom-auth": "Customizing Auth", + "multi-user-auth": "Set up secure multi-user auth for your app", + "custom-auth": "Customize auth", }; From ee97bbbba986852bcefc50385f26014b0d6f0599 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 12:54:02 -0800 Subject: [PATCH 08/11] Rename "APIs" section to "API Reference" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the main navigation section title from "APIs" to "API Reference" to better reflect the content and align with standard documentation conventions. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- app/en/home/_meta.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index d57e1aea4..8dc6fad65 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -69,9 +69,9 @@ export const meta: MetaRecord = { title: "Blog", href: "https://blog.arcade.dev", }, - "-- APIs": { + "-- API Reference": { type: "separator", - title: "APIs", + title: "API Reference", }, api: "API", "arcade-mcp": "Arcade MCP (MCP Server SDK)", From 82713ca754dc18bf8e2e16307112bc9a665731e1 Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 13:05:34 -0800 Subject: [PATCH 09/11] Add Toolkits link and update API key title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add "Toolkits" as external link to "/en/mcp-servers" in Get Started section - Change "API key" to "Get an API key" for clarity and consistency 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- app/en/home/_meta.tsx | 4 ++++ app/en/home/setup/_meta.tsx | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index 8dc6fad65..0969e53f9 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -35,6 +35,10 @@ export const meta: MetaRecord = { quickstarts: "Quickstarts", "common-use-cases": "Common Use Cases", "example-agents": "Example Agents", + toolkits: { + title: "Toolkits", + href: "/en/mcp-servers", + }, glossary: "Glossary", faq: "FAQ", "-- Guides": { diff --git a/app/en/home/setup/_meta.tsx b/app/en/home/setup/_meta.tsx index 78947cf62..ba4470a54 100644 --- a/app/en/home/setup/_meta.tsx +++ b/app/en/home/setup/_meta.tsx @@ -1,4 +1,4 @@ export default { - "api-key": "API key", + "api-key": "Get an API key", "connect-arcade-docs": "Connect Arcade Docs to Your IDE", }; From 7caa3c7b67af48798464939b9da8935c54aaa23f Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 13:15:48 -0800 Subject: [PATCH 10/11] remove blog and status from sidebar and move changelog under Get started --- app/en/home/_meta.tsx | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index 0969e53f9..c357eadfe 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -41,6 +41,7 @@ export const meta: MetaRecord = { }, glossary: "Glossary", faq: "FAQ", + "changelog-page": "Changelog", "-- Guides": { type: "separator", title: "Guides", @@ -60,19 +61,6 @@ export const meta: MetaRecord = { "what-is-agent": "What's an agent?", "auth-and-secrets": "How do auth and secrets work?", "agentic-architecture": "Agentic Architectures & Workflows", - "-- Updates": { - type: "separator", - title: "Updates", - }, - "status-page": { - title: "Status", - href: "https://status.arcade.dev", - }, - "changelog-page": "Changelog", - blog: { - title: "Blog", - href: "https://blog.arcade.dev", - }, "-- API Reference": { type: "separator", title: "API Reference", From c8aa9fc9443a6530f9362c61d1d1a3324396e9fd Mon Sep 17 00:00:00 2001 From: Rachel Lee Nabors Date: Thu, 11 Dec 2025 16:44:49 -0800 Subject: [PATCH 11/11] title case all the sidebar items and spruce up the landing page --- app/en/home/_meta.tsx | 22 +++---- app/en/home/agent-frameworks/_meta.tsx | 2 +- app/en/home/arcade-clients/_meta.tsx | 8 +-- app/en/home/calling-tools/_meta.tsx | 4 +- .../home/calling-tools/mcp-clients/_meta.tsx | 2 +- app/en/home/common-use-cases/_meta.tsx | 9 ++- .../home/configure-arcade-section/_meta.tsx | 4 +- app/en/home/creating-tools/_meta.tsx | 2 +- app/en/home/deployment-hosting/_meta.tsx | 8 +-- app/en/home/landing-page.tsx | 62 +++++++++++-------- app/en/home/security-section/_meta.tsx | 4 +- app/en/home/setup/_meta.tsx | 2 +- app/en/home/what-is-agent/_meta.tsx | 2 +- 13 files changed, 69 insertions(+), 62 deletions(-) diff --git a/app/en/home/_meta.tsx b/app/en/home/_meta.tsx index c357eadfe..56d5559cb 100644 --- a/app/en/home/_meta.tsx +++ b/app/en/home/_meta.tsx @@ -33,8 +33,8 @@ export const meta: MetaRecord = { "about-arcade": "About Arcade", setup: "Setup", quickstarts: "Quickstarts", - "common-use-cases": "Common Use Cases", - "example-agents": "Example Agents", + "common-use-cases": "Common use cases", + "example-agents": "Example agents", toolkits: { title: "Toolkits", href: "/en/mcp-servers", @@ -49,25 +49,25 @@ export const meta: MetaRecord = { "configure-arcade-section": "Configure Arcade", "calling-tools": "Call tools", "creating-tools": "Create tools", - "agent-frameworks": "Agent Frameworks", + "agent-frameworks": "Agent frameworks", "sharing-with-end-users": "Share your agent with end-users", - "observability-platforms": "Observability Platforms", - "deployment-hosting": "Deployment and Hosting", - "security-section": "Security and Compliance", + "observability-platforms": "Observability platforms", + "deployment-hosting": "Deployment and hosting", + "security-section": "Security and compliance", "-- Learn": { type: "separator", title: "Learn", }, - "what-is-agent": "What's an agent?", - "auth-and-secrets": "How do auth and secrets work?", - "agentic-architecture": "Agentic Architectures & Workflows", + "what-is-agent": "What's an agent", + "auth-and-secrets": "How do auth and secrets work", + "agentic-architecture": "Agentic architectures & workflows", "-- API Reference": { type: "separator", title: "API Reference", }, api: "API", - "arcade-mcp": "Arcade MCP (MCP Server SDK)", - "arcade-clients": "Arcade Clients", + "arcade-mcp": "Arcade MCP (MCP server SDK)", + "arcade-clients": "Arcade clients", // Hide auto-discovered directories "api-keys": { display: "hidden", diff --git a/app/en/home/agent-frameworks/_meta.tsx b/app/en/home/agent-frameworks/_meta.tsx index 67eb769d0..135490cfc 100644 --- a/app/en/home/agent-frameworks/_meta.tsx +++ b/app/en/home/agent-frameworks/_meta.tsx @@ -1,7 +1,7 @@ export default { vanilla: "Vanilla", langchain: "LangGraph", - "oai-agents": "OpenAI Agents", + "oai-agents": "OpenAI agents", crewai: "CrewAI", "open-agents": "OpenAgents", "google-adk": "Google ADK", diff --git a/app/en/home/arcade-clients/_meta.tsx b/app/en/home/arcade-clients/_meta.tsx index a7403d26d..ad5938d7d 100644 --- a/app/en/home/arcade-clients/_meta.tsx +++ b/app/en/home/arcade-clients/_meta.tsx @@ -1,6 +1,6 @@ export default { - "python-client": "Python Client", - "javascript-typescript-client": "JavaScript / TypeScript Client", - "go-client": "Go Client", - "java-client": "Java Client", + "python-client": "Python client", + "javascript-typescript-client": "JavaScript / TypeScript client", + "go-client": "Go client", + "java-client": "Java client", }; diff --git a/app/en/home/calling-tools/_meta.tsx b/app/en/home/calling-tools/_meta.tsx index ab428b8ec..fea9fb6e5 100644 --- a/app/en/home/calling-tools/_meta.tsx +++ b/app/en/home/calling-tools/_meta.tsx @@ -8,7 +8,7 @@ export default { "third-party-apps": "Call a tool in your IDEs, MCP clients, or agents", "mcp-clients": "Connect to a MCP client", "evaluation-suite": "Create an evaluation suite to test tools", - "mcp-gateway-auth": "Add authentication to your MCP Gateway", + "mcp-gateway-auth": "Add authentication to your MCP gateway", "-- In custom applications": { type: "separator", title: "In custom applications", @@ -29,5 +29,5 @@ export default { type: "separator", title: "Reference", }, - "direct-api-call": "Direct Third-Party API Call", + "direct-api-call": "Direct third-party API call", }; diff --git a/app/en/home/calling-tools/mcp-clients/_meta.tsx b/app/en/home/calling-tools/mcp-clients/_meta.tsx index 17570ed1d..14b13976f 100644 --- a/app/en/home/calling-tools/mcp-clients/_meta.tsx +++ b/app/en/home/calling-tools/mcp-clients/_meta.tsx @@ -1,5 +1,5 @@ export default { cursor: "Cursor", - "claude-desktop": "Claude Desktop", + "claude-desktop": "Claude desktop", "visual-studio-code": "Visual Studio Code", }; diff --git a/app/en/home/common-use-cases/_meta.tsx b/app/en/home/common-use-cases/_meta.tsx index 82c3c4162..910b56fc7 100644 --- a/app/en/home/common-use-cases/_meta.tsx +++ b/app/en/home/common-use-cases/_meta.tsx @@ -1,8 +1,7 @@ export default { - "build-agent": "Build an agent that uses Arcade MCP Servers.", - "add-external-mcp-servers": "Add external MCP Servers to Arcade.", + "build-agent": "Build an agent that uses Arcade MCP servers", + "add-external-mcp-servers": "Add external MCP servers to Arcade", "build-custom-mcp-server": - "Build a custom MCP Server. that you or others can put in your agent.", - "turn-external-api-into-mcp-server": - "Turn an external API into a MCP Server.", + "Build a custom MCP server that you or others can put in your agent", + "turn-external-api-into-mcp-server": "Turn an external API into a MCP server", }; diff --git a/app/en/home/configure-arcade-section/_meta.tsx b/app/en/home/configure-arcade-section/_meta.tsx index 4c77d9e62..85d132d11 100644 --- a/app/en/home/configure-arcade-section/_meta.tsx +++ b/app/en/home/configure-arcade-section/_meta.tsx @@ -1,6 +1,6 @@ export default { "dashboard-section": "Dashboard", - "create-tenants-section": "Create Organization", - "create-projects-section": "Create Projects", + "create-tenants-section": "Create organization", + "create-projects-section": "Create projects", "arcade-cli-section": "Use Arcade's CLI", }; diff --git a/app/en/home/creating-tools/_meta.tsx b/app/en/home/creating-tools/_meta.tsx index f2d9f53ae..9c20d9e81 100644 --- a/app/en/home/creating-tools/_meta.tsx +++ b/app/en/home/creating-tools/_meta.tsx @@ -6,5 +6,5 @@ export default { "Build tools with agent functionality that doesn't exist", "newest-models": "Ensure tools work with the newest models", "error-handling": "Handle errors", - "registry-early-access": "Registry Early Access", + "registry-early-access": "Registry early access", }; diff --git a/app/en/home/deployment-hosting/_meta.tsx b/app/en/home/deployment-hosting/_meta.tsx index 72d27676a..c2e074fd8 100644 --- a/app/en/home/deployment-hosting/_meta.tsx +++ b/app/en/home/deployment-hosting/_meta.tsx @@ -1,9 +1,9 @@ export default { overview: "Overview", - "cloud-infrastructure": "Use Arcade's Cloud Infrastructure", - "on-premise-mcp": "Use on-premise MCP Servers", - "configure-engine": "Configure Arcade's Engine", + "cloud-infrastructure": "Use Arcade's cloud infrastructure", + "on-premise-mcp": "Use on-premise MCP servers", + "configure-engine": "Configure Arcade's engine", "oauth-provider": "Configure an OAuth provider", "evals-cicd": "Set evals on CI/CD", - "arcade-deploy": "Arcade Deploy", + "arcade-deploy": "Arcade deploy", }; diff --git a/app/en/home/landing-page.tsx b/app/en/home/landing-page.tsx index 90a4d2dcb..26d5a30e7 100644 --- a/app/en/home/landing-page.tsx +++ b/app/en/home/landing-page.tsx @@ -57,7 +57,7 @@ export function LandingPage() { initial={{ opacity: 0, y: 20 }} transition={{ duration: ANIMATION_DURATION }} > - Welcome to Arcade! + Ship AI agents that take action

- Arcade enables your AI agent to securely take real-world actions - through user-specific permissions, pre-built MCP Servers for - Gmail, Slack, GitHub, and more. You can also build your own - agentic tools and MCP servers with our authoring and testing - suite. Arcade is your tool{" "} - engine,{" "} - registry, and{" "} - runtime. -

-

- Get started with a 5-minute quickstart. + Give your agents the ability to send emails, update calendars, + manage files, and interact with any system—not just answer + questions. Arcade handles authentication, permissions, and API + integrations so your agents can work on behalf of real users, + securely.

+
    +
  • + Pre-built integrations Gmail, Slack, GitHub, + and 50+ tools +
    • +
  • + Custom tools Build and deploy your own with our + SDK +
    • +
  • + Built on MCP Model Context Protocol for + universal agent compatibility +
    • +
- + Get Started @@ -119,9 +127,9 @@ export function LandingPage() { size="lg" variant="outline" > - + - Build a tool + Browse the tools @@ -135,13 +143,13 @@ export function LandingPage() { }} >
- Don't write code yourself - let your AI IDE do it for you!
+ Arcade works with your AI IDE: +
- Learn how to give your coding agents access to Arcade.dev's - documentation + Give your coding agent access to Arcade.dev's documentation
@@ -337,28 +345,28 @@ export function LandingPage() {
diff --git a/app/en/home/security-section/_meta.tsx b/app/en/home/security-section/_meta.tsx index fb98eb1e1..216e236f4 100644 --- a/app/en/home/security-section/_meta.tsx +++ b/app/en/home/security-section/_meta.tsx @@ -1,5 +1,5 @@ export default { - "platform-security": "Platform Security", - "enterprise-sso": "Enterprise Single Sign On", + "platform-security": "Platform security", + "enterprise-sso": "Enterprise single sign on", "rbac-config": "Configure role-based access control for your organization", }; diff --git a/app/en/home/setup/_meta.tsx b/app/en/home/setup/_meta.tsx index ba4470a54..d624b2d59 100644 --- a/app/en/home/setup/_meta.tsx +++ b/app/en/home/setup/_meta.tsx @@ -1,4 +1,4 @@ export default { "api-key": "Get an API key", - "connect-arcade-docs": "Connect Arcade Docs to Your IDE", + "connect-arcade-docs": "Connect Arcade docs to your IDE", }; diff --git a/app/en/home/what-is-agent/_meta.tsx b/app/en/home/what-is-agent/_meta.tsx index 3d335b213..5ace1f9a3 100644 --- a/app/en/home/what-is-agent/_meta.tsx +++ b/app/en/home/what-is-agent/_meta.tsx @@ -1,4 +1,4 @@ export default { - "why-agents-call-tools": "Why and how do agents call tools?", + "why-agents-call-tools": "Why and how do agents call tools", "intro-to-tag": "Intro to TAG", };