MCP Tools

This guide explains how to connect your AI agents to external tools using the Model Context Protocol (MCP). MCP is an open standard that enables AI agents to discover and use tools provided by third-party services.

What is MCP

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tool servers. Instead of building custom integrations for each tool, MCP provides a unified way for agents to:

Discover available tools from a server's published capabilities
Understand tool schemas to know what parameters each tool requires
Invoke tools with type-safe parameters
Handle authentication using bearer tokens or OAuth 2.1

MCP tool servers can provide any type of functionality - from accessing external APIs to querying databases to controlling IoT devices. The protocol abstracts away the implementation details, letting your agents focus on using tools rather than managing integrations.

Understanding MCP in Raikoo

In Raikoo, MCP tools are configured at the agent level. When you add an MCP tool to an agent, you specify the server URL and authentication method. The agent then connects to that server and discovers all available tools, which you can selectively enable.

Each MCP tool configuration includes:

Server URL - The endpoint of the MCP server
Transport Type - Either HTTP or SSE (Server-Sent Events)
Authentication - Optional bearer token or OAuth configuration
Tool Selection - Which specific tools from the server to enable

Transport Types

MCP supports two transport protocols for communication between Raikoo and tool servers:

HTTP Transport

Standard HTTP requests with streaming support. Best for:

Simple request/response patterns
Stateless tool invocations
Load-balanced server deployments

Use HTTP when your MCP server supports standard REST-style interactions.

SSE Transport (Server-Sent Events)

Server-sent event streams for real-time updates. Best for:

Long-running operations with progress updates
Real-time data feeds
Persistent connections with lower overhead

Use SSE when your MCP server needs to push updates back to the client during tool execution.

Authentication Methods

MCP tools in Raikoo support two authentication approaches that can be used independently or together.

Bearer Token Authentication

Simple API key authentication using an HTTP Bearer token. The token is included in the Authorization header of every request to the MCP server.

To configure bearer token authentication:

Navigate to your agent's configuration
Go to the Tools section
Click Add Tool and select Add MCP Tools
Enter your server URL
In the Bearer Token field, enter your API key
Continue through the wizard to discover and select tools

Bearer tokens are stored securely in Azure Key Vault, never in the application database.

OAuth 2.1 Authentication

Full OAuth 2.1 support with automatic token refresh and endpoint discovery. OAuth authentication provides:

Authorization Code Flow with PKCE - Industry-standard secure authentication
Automatic Endpoint Discovery - Support for RFC 8414 (OAuth 2.0 Authorization Server Metadata) and OpenID Connect Discovery
Token Management - Automatic refresh when tokens expire
Revocation Support - Clean token revocation when configurations are deleted

To configure OAuth authentication:

Navigate to your agent's configuration
Go to the Tools section
Click Add Tool and select Add MCP Tools
Enter your server URL
Enable OAuth 2.0 checkbox
Either select an existing OAuth configuration or create a new one
Complete the authorization flow
Continue to discover and select tools

OAuth credentials and tokens are encrypted and stored in Azure Key Vault with automatic refresh.

OAuth Configurations

OAuth Configurations are organization-level entities that manage OAuth provider settings. They allow you to:

Define OAuth providers once and reuse them across multiple tools
Store credentials securely in Azure Key Vault with encryption
Manage token lifecycle with automatic refresh
Track authorization status for each configuration

Accessing OAuth Configurations

To access OAuth configurations:

Navigate to your organization's dashboard
Click OAuth Configurations in the left navigation under Organization Settings
You'll see all OAuth configurations defined for your organization

OAuth Configuration Fields

When creating or editing an OAuth configuration, you configure:

Basic Information

Name (required) - A descriptive name for this configuration
Description (optional) - Additional context about the provider
Flow Type - Authorization flow (e.g., authorization_code with PKCE)

Authentication Endpoints

Raikoo supports automatic endpoint discovery via:

RFC 8414 (OAuth 2.0 Authorization Server Metadata) - /.well-known/oauth-authorization-server
OpenID Connect Discovery - /.well-known/openid-configuration

If your provider supports discovery, the wizard will automatically populate endpoints. Otherwise, manually enter:

Authorization Endpoint - URL where users authorize access
Token Endpoint - URL for exchanging codes for tokens
Revocation Endpoint (optional) - URL for revoking tokens

Credentials

Client ID (required) - OAuth client identifier from your provider
Client Secret (required) - OAuth client secret (stored encrypted in Azure Key Vault)
Scopes (optional) - Space-separated list of OAuth scopes to request

Token Management

Once authorized, OAuth configurations manage tokens automatically:

Access tokens are encrypted and stored in Azure Key Vault
Refresh tokens are used to obtain new access tokens when they expire
Token expiration is tracked and tokens are refreshed before they expire
Authorization status shows whether the configuration is active, expired, or revoked

Creating OAuth Configurations

OAuth configurations can be created in two ways:

Via MCP Tool Wizard

When adding MCP tools to an agent, if you enable OAuth and don't select an existing configuration, the wizard will guide you through creating a new one:

The wizard attempts automatic discovery of OAuth endpoints
If discovery succeeds, endpoints are pre-filled
If discovery fails, you manually configure endpoints
Enter your client credentials
Complete the authorization flow in your browser
The configuration is created and immediately used for the MCP tool

Directly from OAuth Configurations Page

You can also create standalone OAuth configurations:

Navigate to OAuth Configurations in your organization
Click Create
Fill in the configuration details
Complete authorization
The configuration becomes available for any MCP tool or other OAuth-enabled feature

Adding MCP Tools to Agents

To add MCP tools to an agent:

Navigate to your agent's configuration page
Go to the Tools section
Click Add Tool and select Add MCP Tools
The MCP Tool Wizard will guide you through the process

Step 1: Server Configuration

Enter your MCP server details:

MCP Server URL - The base URL of your MCP server
Transport Type - Select HTTP or SSE
Bearer Token (optional) - API key for simple authentication
Enable OAuth 2.0 (optional) - Check to use OAuth authentication
OAuth Configuration (if OAuth enabled) - Select an existing configuration or create a new one

If you enable OAuth without selecting an existing configuration, the wizard will attempt automatic discovery and guide you through setup.

Step 2: OAuth Setup (if creating new configuration)

If automatic discovery succeeds:

Endpoints are pre-filled from server metadata
Recommended flow type is selected
You proceed directly to entering credentials

If automatic discovery fails:

Select a setup method (manual or preset)
Configure endpoints manually or use a provider preset
Enter configuration details

Step 3: OAuth Credentials (if using OAuth)

Enter your OAuth client credentials:

Client ID - From your OAuth provider
Client Secret - From your OAuth provider (stored encrypted)
Scopes (optional) - Space-separated list of scopes

Click Authorize to open the OAuth authorization flow in your browser. Once authorized, the wizard automatically proceeds to tool discovery.

Step 4: Tool Discovery

The wizard connects to your MCP server and discovers all available tools. This happens automatically after successful authentication (or immediately if using bearer token or no auth).

A countdown indicates automatic progression to tool selection, or you can click Next to proceed immediately.

Step 5: Tool Selection

Review and select the tools you want to enable for your agent:

Tool List - All discovered tools with their descriptions
Selection - Check the tools you want to enable
Display Name - Customize how each tool appears to the agent
Function Name - Customize the function name (defaults to tool name)
Function Name Prefix (optional) - Add a prefix to all selected tools (e.g., "github_" for "github_list_repos")
OAuth Configuration Name (if new) - Confirm or rename the OAuth configuration

Use Select All or Deselect All for bulk operations.

Click Add Tools to add the selected tools to your agent.

Managing Existing MCP Tools

When you reopen the MCP tool wizard with existing tools from the same server/auth configuration:

Tools already enabled are pre-selected
Unchecking a tool will remove it from the agent
Checking a new tool will add it to the agent
The wizard tracks additions and removals

This allows you to manage all tools from a specific MCP server in one place.

Using MCP Tools

Once configured, agents can use MCP tools naturally in conversations and workflows. The tools appear in the agent's tool roster with their custom display names and descriptions.

Example: Using a GitHub MCP Tool

User: "Create an issue in the docs repository"

Agent: Uses github_create_issue tool "I've created issue #42 in the docs repository with the title and description you specified."

Example: Using a Database MCP Tool

User: "Query the production database for recent orders"

Agent: Uses db_query tool "Found 15 orders placed in the last hour, total value $3,240."

Best Practices

Server Trust and Security

Verify server URLs - Only connect to MCP servers you trust
Use HTTPS - Always use encrypted connections for production deployments
Rotate credentials - Periodically update bearer tokens and OAuth credentials
Review tool permissions - Understand what each tool can do before enabling it

Authentication Method Selection

Use bearer tokens for simple scenarios with API keys
Use OAuth for production deployments requiring user-specific access
Use both when a server requires an API key plus user context

OAuth Configuration Management

Descriptive names - Use clear names that indicate the provider and purpose
Monitor token status - Check OAuth configuration status regularly
Reauthorize promptly - When tokens expire or are revoked, reauthorize quickly to restore tool access
Centralize configurations - Create organization-level OAuth configs for reuse across agents

Tool Organization

Use function name prefixes - Add prefixes like "github_" or "slack_" to avoid name conflicts when using multiple MCP servers
Customize display names - Make tool names clear and descriptive for your team
Enable selectively - Only enable the tools your agent needs, not all available tools

Token Expiry Monitoring

OAuth tokens have expiration times set by the provider
Raikoo automatically refreshes tokens before they expire
If refresh fails (e.g., refresh token revoked), the OAuth configuration status becomes "needs_reauth"
Agents using that configuration will fail authentication until reauthorized
Monitor the OAuth Configurations page for configurations requiring reauthorization

Troubleshooting Common Issues

Discovery Fails

Symptoms: Tool discovery times out or returns an error

Solutions:

Verify the server URL is correct and accessible
Check that the transport type matches the server's supported protocol
Ensure authentication credentials are valid
Verify firewall rules allow connections to the MCP server

OAuth Authorization Fails

Symptoms: Browser redirect fails or authorization error occurs

Solutions:

Verify client ID and client secret are correct
Check that redirect URIs are configured in your OAuth provider
Ensure the authorization endpoint URL is correct
Try manual endpoint configuration if automatic discovery fails

Tool Invocation Fails

Symptoms: Tools are discovered but fail when invoked by the agent

Solutions:

Check that OAuth tokens are still valid (look for "needs_reauth" status)
Verify bearer token hasn't expired or been revoked
Review tool invocation logs for specific error messages
Ensure required tool parameters are being provided by the agent

Token Refresh Fails

Symptoms: OAuth configuration shows "needs_reauth" status

Solutions:

Navigate to OAuth Configurations page
Click the configuration requiring reauthorization
Complete the authorization flow again
Tools using this configuration will resume working

Next Steps

Now that you understand MCP tools, you can:

Explore MCP servers - Find or build MCP servers for the tools you need
Configure agents - Add MCP tools to enable new capabilities
Create workflows - Build workflows that leverage MCP tools
Monitor usage - Track how agents are using MCP tools in production

MCP tools provide a flexible, standards-based way to extend your agents with any external capability. By properly configuring authentication and following best practices, you can safely enable powerful integrations.