How to Use MCP with Open Agents SDK through Arcade

Open Agent Platform integrates LangGraph for agent orchestration, Model Context Protocol for tool calling, and Arcade for authentication. This guide shows you how to configure MCP servers through Arcade to build production-ready agents.

Architecture Overview

The stack consists of three layers:

• LangGraph: Graph-based agent orchestration and state management
• Arcade MCP Server: Handles OAuth 2.0 authentication and tool execution via HTTP streamable transport
• Target APIs: Gmail, Slack, Calendar, GitHub, and 100+ integrated services

Arcade functions as both the MCP server and authentication provider. When your agent calls a tool, Arcade manages the OAuth flow server-side, ensuring tokens never reach the language model.

Prerequisites

Required setup:

• Arcade account with API key
• LangGraph Platform deployment (cloud or self-hosted)
• Node.js 18+ and Python 3.8+
• Supabase project for user authentication
• Git for cloning repositories

Optional for local development:

• Docker for containerized deployments
• Redis for session management
• PostgreSQL for persistent storage

Install Arcade SDK

Install the Arcade Python client:

pip install arcadepy arcade-ai

For JavaScript projects:

npm install @arcadeai/arcadejs

Verify installation:

from arcadepy import AsyncArcade
client = AsyncArcade()

Get your API key from the Arcade dashboard.

Configure MCP Server Connection

Navigate to your Open Agent Platform installation at apps/web/ and set environment variables:

NEXT_PUBLIC_MCP_SERVER_URL=https://api.arcade.dev/v1/mcps/arcade-anon
NEXT_PUBLIC_MCP_AUTH_REQUIRED=true

The URL must NOT end with /mcp - the platform appends this automatically during requests.

Authentication Setup

Arcade's MCP server requires authentication for multi-user tool execution. The flow works as follows:

1. Web client requests the proxy route at /api/oap_mcp
2. Proxy exchanges Supabase JWT for Arcade MCP access token
3. Access token authenticates all subsequent MCP requests
4. Token expires after one hour by default

Configure additional variables:

# LangGraph Deployment
NEXT_PUBLIC_DEPLOYMENTS='[{
  "id": "deployment-id",
  "tenantId": "tenant-id",
  "deploymentUrl": "https://your-deployment.com",
  "name": "Production",
  "isDefault": true,
  "defaultGraphId": "agent"
}]'

# Supabase Auth
NEXT_PUBLIC_SUPABASE_URL=https://project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

Restart your platform instance after configuration changes.

Deploy Sample Agents

Clone the pre-built agent templates:

# Tools Agent
git clone https://github.com/langchain-ai/open-agent-platform-tools-agent.git
cd open-agent-platform-tools-agent

# Supervisor Agent
git clone https://github.com/langchain-ai/open-agent-platform-supervisor-agent.git
cd open-agent-platform-supervisor-agent

Deploy each agent to your LangGraph Platform following the repository README instructions. Note the deployment IDs and URLs from the /info endpoint.

Create Your First Agent

Agent Configuration

Each agent requires:

• Model selection (GPT-4, Claude, etc.)
• System prompt
• Temperature and token limits
• Tool attachments from Arcade MCP servers
• Optional RAG configuration

Google Calendar Agent Example

Model settings:

• Model: gpt-4o-mini
• Temperature: 0.3
• Max tokens: 2000

System prompt:

You are a calendar management assistant. Create, update, and list Google Calendar events based on user requests. Confirm all actions before execution.

Attached tools:

• Google Create Event
• Google List Events
• Google List Calendars

The agent requests user authorization automatically when calling Google Calendar APIs.

OAuth Flow Execution

When an agent calls a tool requiring authentication:

1. LangGraph determines tool call is needed
2. Arcade checks user authorization status
3. If unauthorized, Arcade returns authorization URL
4. User completes OAuth consent in browser
5. Arcade stores tokens server-side
6. Tool executes with user-scoped credentials
7. Results return to agent

Tokens remain server-side throughout this flow. The language model only sees tool definitions and results.

Authorization States

Authorized: User completed OAuth, tokens valid, tool executes immediately

Authorization Required: User must complete OAuth before tool execution

Token Expired: Arcade automatically refreshes using stored refresh tokens

Work with Arcade MCP Servers

Arcade provides production-ready MCP servers for popular services. View the full list at Arcade MCP Servers.

Available Toolkits

Gmail: Send emails, search messages, create drafts, manage labels

Google Calendar: Create events, list calendars, update meetings

Slack: Post messages, read channels, manage workspaces

GitHub: Repository management, issues, pull requests

Linear: Issue tracking, project management

Notion: Database operations, page creation

Each toolkit includes multiple tools accessible through MCP protocol with automatic OAuth scoping.

Query Available Tools

List tools from a specific toolkit:

from arcadepy import AsyncArcade

async def get_toolkit_tools():
    client = AsyncArcade()
    tools = await client.tools.list(
        toolkit="gmail",
        limit=30
    )

    for tool in tools.items:
        print(f"{tool.name}: {tool.description}")
        print(f"Auth required: {tool.requires_auth}")

This returns MCP-formatted tool definitions with parameter schemas.

Handle Tool Execution

Python Implementation

from agents import Agent, Runner
from arcadepy import AsyncArcade
from agents_arcade import get_arcade_tools
from agents_arcade.errors import AuthorizationError

async def run_gmail_agent():
    client = AsyncArcade()
    tools = await get_arcade_tools(
        client,
        toolkits=["gmail"]
    )

    agent = Agent(
        name="Email Assistant",
        instructions="Manage user email efficiently",
        model="gpt-4o-mini",
        tools=tools
    )

    try:
        result = await Runner(agent=agent).run(
            input="Send email to team@company.com",
            user_id="user_123"
        )
        return result
    except AuthorizationError as e:
        print(f"Authorization needed: {e.authorization_url}")
        # Present URL to user, then retry after auth

The user_id parameter ensures each user maintains separate OAuth tokens.

JavaScript Implementation

import Arcade from "@arcadeai/arcadejs";
import { executeOrAuthorizeZodTool, toZod } from "@arcadeai/arcadejs/lib";
import { Agent, run } from "@openai/agents";

const client = new Arcade();

const googleToolkit = await client.tools.list({
    toolkit: "gmail",
    limit: 30
});

const tools = toZod({
    tools: googleToolkit.items,
    client,
    userId: "user_123"
});

const agent = new Agent({
    name: "Email Agent",
    instructions: "Help with email management",
    model: "gpt-4o-mini",
    tools
});

const result = await run(agent, {
    input: "Draft email to team"
});

Multi-Agent Workflows

Open Agent Platform supports agent supervision where one agent coordinates multiple specialized agents.

Supervisor Pattern

Supervisor Agent: Routes tasks to appropriate worker agents

Worker Agents: Handle specific domains (email, calendar, data)

Shared State: LangGraph manages state across interactions

Configuration:

supervisor = Agent(
    name="Task Coordinator",
    instructions="Route tasks to specialized agents",
    model="gpt-4",
    tools=supervisor_tools
)

email_agent = Agent(
    name="Email Specialist",
    model="gpt-4o-mini",
    tools=gmail_tools
)

calendar_agent = Agent(
    name="Calendar Specialist",
    model="gpt-4o-mini",
    tools=calendar_tools
)

Each worker agent maintains independent tool attachments and model configurations while the supervisor orchestrates workflow.

Production Configuration

Rate Limits

Arcade enforces tool execution quotas:

• Free: 100 calls/month
• Starter: 5,000 calls/month
• Growth: 100,000 calls/month
• Enterprise: Custom quotas

Monitor usage through the Arcade dashboard.

Security Setup

Implement these measures:

• Store API keys in secure key management systems
• Enable audit logging for tool executions
• Configure rate limiting at application level
• Verify webhook signatures for auth callbacks
• Regular OAuth scope audits

Monitoring Metrics

Track in production:

• Tool execution success/failure rates
• Authorization completion rates
• API latency per tool
• Token refresh frequency
• User quota consumption

Configure webhooks in Arcade dashboard for real-time alerts.

Update Agent MCP URLs

When changing MCP server configuration, update existing agents:

cd apps/web
npx tsx scripts/update-agents-mcp-url.ts

Required environment variables:

NEXT_PUBLIC_MCP_SERVER_URL=new-url
NEXT_PUBLIC_DEPLOYMENTS=deployments-json
LANGSMITH_API_KEY=langsmith-key

The script:

• Fetches all agents from configured deployments
• Identifies agents with MCP support
• Updates MCP URLs if changed
• Uses LangSmith API for authentication

Troubleshoot Common Issues

MCP Connection Failures

Verify:

• NEXT_PUBLIC_MCP_SERVER_URL formatted without trailing /mcp
• Network access to Arcade servers
• MCP authentication settings match configuration
• Arcade status page for service health

Authorization Loops

Check:

• user_id consistency across requests
• Token storage configuration in Arcade dashboard
• OAuth redirect URLs match registered callbacks
• Token expiration settings

Tool Execution Timeouts

Solutions:

• Increase timeout in agent settings
• Check API rate limits on target services
• Verify network latency between components
• Review Arcade logs for specific errors

Missing Tools

Confirm:

• Toolkit names match available MCP servers
• MCP server connection established
• Tool filtering parameters correct
• Proper authentication to MCP server

Build Custom Tools

Create custom tools using the Arcade Tool SDK:

from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Google

@tool(
    requires_auth=Google(
        scopes=["https://www.googleapis.com/auth/gmail.send"]
    )
)
async def send_email(
    context: ToolContext,
    to: str,
    subject: str,
    body: str
) -> dict:
    # Implementation here
    pass

Register custom tools in your Arcade deployment configuration and attach them to agents through the MCP server.

Next Steps

Expand your agent capabilities:

• Build custom tools with the Arcade Tool SDK
• Configure RAG integration for knowledge-enhanced agents
• Deploy multi-agent supervisor workflows
• Scale horizontally with load balancing
• Integrate additional MCP servers

The combination of Open Agent Platform orchestration, MCP standardization, and Arcade authentication enables production-ready AI agents that securely interact with real-world systems.