Skip to main content

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 HTTP/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​

  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 stored securely in Parameter Store
  • Sent as Authorization: Bearer YOUR_TOKEN

3. OAuth 2.1 (Dynamic Client Registration)

  • For servers supporting OAuth 2.1 with dynamic clients
  • Provide the authorization server URL
  • Vectorize handles the OAuth flow automatically
  • Users authenticate once per organization

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

Test Connection​

After configuration:

  1. Click Test Connection to verify setup
  2. Vectorize will attempt to connect and discover tools
  3. If successful, available tools will be displayed

Enable Tools​

Once connected:

  1. Review the discovered tools
  2. Toggle on/off individual tools for your agent
  3. Tools are immediately available to the agent

OAuth 2.1 Authentication Flow​

For servers supporting OAuth 2.1 with dynamic client registration:

Initial Setup​

  1. Enter the OAuth authorization server URL
  2. Click Connect with OAuth
  3. Vectorize registers as a dynamic client
  4. You're redirected to authenticate

Authorization Process​

  1. Dynamic Registration - Vectorize registers with the auth server
  2. User Consent - You authorize Vectorize to access the MCP server
  3. Token Storage - Tokens are stored per organization
  4. Automatic Refresh - Tokens are refreshed as needed

Redirect Handling​

After OAuth authorization:

  • You're redirected back to the Tools settings page
  • The connection status is updated
  • Tools are discovered automatically

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 a Linear issue for the bug in the login system"
  2. Tool Selection - Agent identifies the create-linear-issue tool
  3. Parameter Extraction - Agent extracts title, description from context
  4. Execution - Vectorize proxies the request to the Linear MCP server
  5. Response - Issue details returned and shown to user

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

Update Configuration​

To modify a server:

  1. Click the server card
  2. Update URL, authentication, or settings
  3. Test connection to verify changes

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

Security Considerations​

HTTPS Required​

  • All external MCP servers must use HTTPS
  • HTTP endpoints are not supported

Token Storage​

  • Tokens and customer headers are encrypted at rest
  • Access is scoped to your organization

Example: Linear Integration​

Here's how to connect the Linear MCP server:

  1. Add MCP Server

    • Name: "Linear Project Management"
    • URL: https://linear-mcp.example.com/mcp
    • Auth: OAuth 2.1

  2. Authenticate

    • Click "Connect with OAuth"
    • Authorize access to your Linear workspace
    • Return to Vectorize

  3. Enable Tools

    • create-issue - Create new Linear issues
    • update-issue - Modify existing issues
    • search-issues - Find issues by criteria

  4. Use in Agent

    User: "Create a high priority bug for the login timeout issue"
    Agent: "I'll create a Linear issue for this bug."
    [Uses create-issue tool]
    Agent: "Created issue LIN-1234: Login timeout issue (High priority)"

What's Next?​

Was this page helpful?