External MCP Tools for Chat Agents

Connect your Chat agents (Chat Apps and Chat Widgets) to external MCP servers to access custom tools and integrations beyond Vectorize's built-in capabilities. This feature enables Chat agents to use tools from any MCP-compatible server alongside your Vectorize retrieval tools.

Important

This feature is only available for Chat agents (Chat Apps and Chat Widgets).

Overview

External MCP tools allow your Chat agents to:

• Connect to third-party MCP servers via HTTPS
• Use custom tools for specialized tasks (e.g., Linear issue creation, GitHub operations)
• Authenticate using various methods (Bearer tokens, OAuth 2.1, custom headers)
• Combine external tools with Vectorize retrieval for comprehensive agent capabilities

How It Works

When you configure an external MCP server:

1. Discovery - Vectorize connects to the MCP server and discovers available tools
2. Integration - Tools are made available to your agent alongside Vectorize tools
3. Execution - When the agent needs a tool, Vectorize proxies the request to the external server
4. Results - Responses are returned to the agent for processing

Adding External MCP Servers

Navigate to Tools Settings

1. Open your Chat agent's admin panel (Chat App or Widget)
2. Click Tools & Functions in the sidebar
3. You'll see sections for Vectorize tools and MCP servers

Add a New MCP Server

Click Add MCP Server to configure a new external server:

Basic Configuration

• Server Name: A descriptive name for this server
• URL: The HTTPS endpoint of the MCP server
  • Must use HTTPS for security
  • Example: https://api.example.com/mcp

Authentication Options

Choose the authentication method your MCP server requires:

1. No Authentication

• For public MCP servers
• No additional configuration needed

2. Bearer Token

• Provide a static API key or token
• Token is encrypted and stored securely
• Sent as Authorization: Bearer YOUR_TOKEN

3. OAuth 2.1

• For servers supporting OAuth 2.1 authentication
• Two modes supported:
  • Dynamic Client Registration: Vectorize automatically registers as an OAuth client (preferred)
  • Static Client Credentials: For servers like GitHub that require pre-registered OAuth apps
• Vectorize handles the OAuth flow and token refresh automatically
• Admin users authenticate once per agent

4. Custom Headers

• For servers requiring custom authentication headers
• Add any headers needed (e.g., X-API-Key, X-Client-ID)
• Values are stored securely

What Happens After Adding a Server

After clicking Add Server:

For non-OAuth servers (Bearer Token, Custom Headers, None):

1. Server is created and connection is tested automatically
2. If successful, tools are discovered and the server status shows "Active"
3. If connection fails, server status shows "Error" with details
4. You're returned to the Tools settings page

For OAuth 2.1 servers:

1. Server is created
2. You're redirected to authorize the connection
3. After authorization, you're returned to Tools settings
4. Tools are automatically discovered

Managing Tools

Once a server is connected:

1. Click the server card to expand and view discovered tools
2. Toggle individual tools on/off for your agent
3. Click Refresh/Discover Tools (refresh icon) to update the tool list
4. Use Enable All or Disable All buttons to toggle all tools at once
5. Tools are immediately available to the agent when enabled

OAuth 2.1 Authentication Flow

Vectorize supports two OAuth 2.1 authentication approaches:

Dynamic Client Registration (Recommended)

For MCP servers that support OAuth 2.1 dynamic client registration:

1. Add the MCP server and select OAuth 2.1 as the auth type
2. Leave the Client ID and Client Secret fields empty
3. Click Add Server
4. Vectorize automatically registers as an OAuth client with the server
5. You're redirected to authorize access
6. After authorization, you're returned to the Tools settings
7. Tools are discovered automatically

This approach requires no pre-configuration and works with any OAuth 2.1 server supporting dynamic client registration.

Static Client Credentials

For services like GitHub that require pre-registered OAuth apps:

1. Create an OAuth app in the service's developer settings
2. Set the redirect URI to: https://agents.vectorize.io/api/mcp-servers/oauth2/callback
3. Note your Client ID and Client Secret
4. In Vectorize, add the MCP server and select OAuth 2.1
5. Enter your Client ID and Client Secret
6. Click Add Server
7. You're redirected to authorize the app
8. After authorization, you're returned to the Tools settings

Required OAuth Scopes: Check the MCP server's documentation for required scopes. For example:

• GitHub MCP: repo, workflow

Token Management

After successful OAuth authorization:

• Access and refresh tokens are encrypted and stored per agent
• Tokens are automatically refreshed before expiration
• If token refresh fails, the server status changes to "error"
• Click Authorize with OAuth 2.1 to re-authenticate

Using External Tools

In Chat Agents

External tools work seamlessly in chat interfaces:

• The LLM sees all available tools (Vectorize + external)
• Tools are invoked based on user queries
• Results are incorporated into responses

Tool Execution Flow

1. User Query - "Create an issue for the bug in the login system"
2. Tool Selection - Agent identifies the appropriate tool from enabled MCP tools
3. Parameter Extraction - Agent extracts required parameters from context
4. Execution - Vectorize proxies the request to the external MCP server
5. Response - Tool results returned and incorporated into agent's response

Managing MCP Servers

View Server Status

In the Tools settings:

• Active - Server is connected and tools are available
• Inactive - Server is configured but disabled
• Error - Connection or authentication issues

Refresh Tools

To update the tool list from an MCP server:

1. Click the Refresh/Discover Tools icon (refresh icon) on the server card
2. Vectorize will re-query the server for available tools
3. New or updated tools will appear in the tool list

Remove a Server

To delete a server:

1. Click the delete icon on the server card
2. Confirm removal
3. All associated tools are removed from the agent

Technical Details

Supported Transport Protocols

Vectorize automatically detects and supports multiple MCP transport protocols:

1. JSON-RPC over HTTP

• Standard MCP protocol over HTTPS
• Most common for custom MCP servers
• Bidirectional request/response

2. Server-Sent Events (SSE)

• For servers ending in /sse
• Supports streaming responses
• Ideal for long-running operations

3. Streamable HTTP

• For servers ending in /mcp (e.g., Linear)
• Efficient for real-time data
• Supports progress updates

The transport type is automatically detected based on the server URL. No configuration needed.

Tool Discovery

When you connect an MCP server:

1. Vectorize calls the initialize method to establish connection
2. Calls tools/list to discover available tools
3. Stores the discovered tools and timestamps when they were discovered
4. Click Refresh/Discover Tools to re-discover tools from the server

Tool Execution

When an agent uses an external tool:

1. Agent determines which tool to call based on user query
2. Vectorize validates the tool parameters
3. Request is proxied to the external MCP server with authentication
4. Response is returned to the agent for processing
5. Agent incorporates results into its response

Security Considerations

HTTPS Required

• All external MCP servers must use HTTPS
• HTTP endpoints are rejected for security
• Self-signed certificates are not supported

Credential Storage

• All credentials are encrypted at rest
• OAuth tokens automatically refreshed before expiration
• MCP servers are configured per agent by admin users
• Once configured, all users of the chat agent can use the connected tools
• Credentials never exposed in logs or API responses

Request Security

• 30-second timeout on all MCP requests
• Requests include authentication headers automatically
• OAuth tokens refreshed automatically before expiration
• Session IDs maintained for stateful servers (e.g., GitHub MCP)

Example Integrations

Example: Custom MCP Server

Connect a custom MCP server with Bearer token authentication:

1. Add MCP Server

   • Name: "My Custom Tools"
   • URL: https://mcp.example.com
   • Auth: Bearer Token
   • Token: Your API key

2. What Happens

   • Server is tested automatically
   • Tools are discovered
   • Server status shows "Active" if successful

3. Available Tools

   • Tools depend on your MCP server implementation
   • Each tool's description helps the agent know when to use it

4. Example Usage

   User: "Create a ticket for the login issue"
   Agent: "I'll create a ticket using the custom tools."
   [Uses create-ticket tool]
   Agent: "Created ticket #1234: Login timeout issue"

GitHub Integration

Connect GitHub for repository operations:

1. Create GitHub OAuth App

   • Go to Settings → Developer settings → OAuth Apps
   • New OAuth App with:
     • Application name: "Vectorize Chat Agent"
     • Homepage URL: https://agents.vectorize.io
     • Callback URL: https://agents.vectorize.io/api/mcp-servers/oauth2/callback
   • Note the Client ID and generate a Client Secret

2. Add MCP Server in Vectorize

   • Name: "GitHub"
   • URL: https://mcp.github.com/mcp (or your GitHub MCP server)
   • Auth: OAuth 2.1 (Static Credentials)
   • Enter Client ID and Client Secret

3. Available Tools (depends on GitHub MCP server)

   • search-code - Search code across repositories
   • create-issue - Create GitHub issues
   • create-pull-request - Create pull requests
   • list-repositories - List accessible repositories

4. Example Usage

   User: "Search for authentication code in our repos"
   Agent: "I'll search our GitHub repositories for authentication-related code."
   [Uses search-code tool]
   Agent: "Found 15 files containing authentication logic across 3 repositories..."

Troubleshooting

Server Status: Error

If an MCP server shows "Error" status:

Check Authentication

• Bearer Token: Verify the token is correct and hasn't expired
• OAuth 2.1: Click Authorize with OAuth 2.1 to re-authenticate
• Custom Headers: Ensure header values are valid

Test Connection

• When a server status is "Error", a Test Connection icon (WiFi icon) appears on the server card
• Click it to retry the connection
• Review the error message for specifics
• Check that the server URL is accessible from the internet

Common Error Messages

• "Connection timeout": Server took too long to respond (>30s). Check if server is running.
• "Authentication required": Credentials are invalid or missing. Update auth configuration.
• "OAuth authentication required": OAuth token expired or revoked. Re-authorize the connection.
• "Server endpoint not found (404)": URL is incorrect. Verify the MCP server endpoint.
• "Access forbidden (403)": API key lacks required permissions. Check OAuth scopes or API key permissions.
• "Network error": Server is unreachable. Verify URL and ensure server is online.

Tools Not Appearing

If tools aren't showing after connecting:

1. Click Refresh/Discover Tools on the server card
2. Check that the server status is "Active"
3. Verify the MCP server implements tools/list method correctly
4. Check browser console for errors

Tool Execution Failures

If tools fail during agent conversations:

1. Check the server status - it may have become disconnected
2. Review tool parameter requirements - agent may be passing invalid data
3. Verify OAuth token hasn't expired - re-authorize if needed
4. Check rate limits on the external service

OAuth Redirect Issues

If OAuth redirects aren't working:

1. Verify redirect URI matches exactly: https://agents.vectorize.io/api/mcp-servers/oauth2/callback
2. Check that your OAuth app is active in the service's developer settings
3. Clear browser cookies and try again

Tools Not Being Used

If the agent isn't using configured tools:

1. Verify tools are enabled (toggle should be on)
2. Check tool descriptions - agent uses them to decide when to invoke tools
3. Review system prompt - it should encourage tool usage when appropriate
4. Test with explicit requests: "Use the create-issue tool to create a ticket for..."

Quick Reference

Supported Authentication Methods

Method	Use Case	Configuration Required
None	Public MCP servers	Server URL only
Bearer Token	API key authentication	API key/token
OAuth 2.1 (Dynamic)	Services supporting dynamic registration	Server URL only
OAuth 2.1 (Static)	GitHub and other pre-registered apps	Client ID + Secret
Custom Headers	Services with custom auth	Header key-value pairs (JSON)

OAuth Redirect URI

When configuring OAuth apps in external services, use this redirect URI:

https://agents.vectorize.io/api/mcp-servers/oauth2/callback

Transport Protocol Detection

Server URL Pattern	Transport Type	Example
Ends with /sse	Server-Sent Events	https://api.example.com/sse
Ends with /mcp	Streamable HTTP	https://mcp.linear.app/mcp
Other HTTPS URL	JSON-RPC	https://mcp.example.com

What's Next?

• Creating Agent Tools - Build custom Vectorize tools
• MCP Protocol Overview - Understand MCP concepts
• Chat Agent Setup - Configure chat interfaces