Skip to main content

Create an MCP Agent

This guide walks you through creating and configuring an MCP agent to connect your Vectorize pipelines to AI desktop tools.

Prerequisites

Before you begin, you'll need:

  1. A Vectorize account
  2. An API access token (how to create one)
  3. Your organization ID (see below)
  4. A pipeline ID (see below)

Finding your Organization ID

Your organization ID is in the Vectorize platform URL:

https://platform.vectorize.io/organization/[YOUR-ORG-ID]

For example, if your URL is:

https://platform.vectorize.io/organization/ecf3fa1d-30d0-4df1-8af6-f4852bc851cb

Your organization ID is: ecf3fa1d-30d0-4df1-8af6-f4852bc851cb

Finding your Pipeline ID

Navigate to your pipeline in the Vectorize platform. The pipeline ID is shown in:

  • The URL: https://platform.vectorize.io/organization/[org-id]/pipeline/[PIPELINE-ID]
  • The pipeline details page
  • The "Connect" tab of your pipeline

Step 1: Create the MCP Agent​

  1. Log into your Vectorize workspace
  2. Click Agents in the left sidebar
  3. Click Create Agent

Select MCP Agent Type​

You'll see three agent types. Select Model Context Protocol (MCP):

  • Purpose: Connect to AI desktop tools like Claude Desktop, Claude Code, or Cursor
  • No UI: Integrates directly into existing applications
  • API-based: Uses secure API keys for authentication

Configure Basic Settings​

  1. Agent Name: Choose a descriptive name (e.g., "Engineering Docs Assistant")
  2. Description: Explain what this agent provides access to
  3. Click Create Agent

Your MCP agent is now created but needs functions to be useful.

Step 2: Configure Agent Actions​

Configure what actions your MCP agent can perform. These actions become tools in your AI assistants.

Configure Your First Action​

In your MCP agent settings:

Basic Information​

  • Action Name: Use lowercase with hyphens (e.g., search-docs)
  • Description: Clear explanation for the AI to understand when to use this tool
  • Pipeline: Select which pipeline this action queries

Example Configuration​

Name: search-engineering-docs
Description: Search internal engineering documentation, architecture guides, and API references
Pipeline: engineering-knowledge-base

Add Multiple Actions​

  1. Configure additional actions as needed
  2. Each action provides a different capability
  3. Actions are automatically available to connected tools

Step 3: Generate API Keys​

Your MCP agent needs API keys for secure access.

Create an API Key​

  1. Go to your agent's detail page
  2. Navigate to the Agent API Keys section
  3. Click Create New Key
  4. Give it a descriptive name (e.g., "Claude Desktop Key")
  5. Click Create Key
warning

Save your API key immediately - you won't be able to see it again! Store it securely in a password manager.

Copy Configuration​

After creating the key, Vectorize provides a ready-to-use configuration. Copy this for the next step.

Step 4: Connect Your Tool​

Now connect your MCP agent to your preferred AI tool. You can use either the hosted Remote MCP server (recommended) or run a local server:

Connection Options​

Use Vectorize's hosted MCP server - no infrastructure to manage:

{
  "mcpServers": {
    "vectorize": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://agents.vectorize.io/api/agents/YOUR_AGENT_ID/mcp",
        "--header", "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

Option 2: Local MCP Server​

For development or special requirements, see Local MCP Server Setup.

General Connection Steps​

  1. Locate your tool's MCP configuration file
  2. Add your agent's configuration (provided when you created the API key)
  3. Restart the tool
  4. Your agent's actions appear as available tools

Step 5: Test Your Integration​

Once connected, verify your MCP agent is working:

In Claude Desktop​

  1. Look for your agent in the tools menu
  2. Ask a question that would use your function
  3. Claude should automatically invoke the appropriate tool

In Cursor​

  1. Check the MCP panel shows your agent
  2. Ask Cursor about topics in your pipeline
  3. It should retrieve relevant information

Managing Your MCP Agent​

View Connected Functions​

On your agent's detail page, you can see:

  • All connected functions
  • Usage statistics
  • Recent queries
  • Error logs (if any)

Update Functions​

To modify what your agent can do:

  1. Go to Metadata → Functions
  2. Edit existing functions or create new ones
  3. Changes take effect immediately

Monitor Usage​

Track how your MCP agent is being used:

  • Query volume
  • Response times
  • Most-used functions
  • User feedback

Best Practices​

Function Design​

  • Clear Names: Use descriptive, action-oriented names
  • Detailed Descriptions: Help the AI understand when to use each function
  • Focused Purpose: Each function should do one thing well
  • Useful Parameters: Add filters that make sense for your use case

Security​

  • Rotate Keys: Periodically refresh API keys
  • Limit Scope: Only expose necessary data through functions
  • Monitor Access: Review usage logs regularly
  • Test Thoroughly: Verify functions return appropriate data

Performance​

  • Optimize Pipelines: Ensure underlying pipelines are fast
  • Use Filters: Configure functions to return focused results
  • Cache When Possible: Leverage Vectorize's built-in caching

Troubleshooting​

Agent Not Appearing in Tool​

  • Verify API key is correctly configured
  • Check the tool has been restarted
  • Ensure the agent has at least one function

No Results Returned​

  • Confirm pipeline has indexed documents
  • Check function configuration and filters
  • Verify metadata filters aren't too restrictive
  • Test the pipeline directly in Vectorize UI

Connection Errors​

  • Validate API key hasn't expired
  • Check network connectivity
  • Verify correct endpoint URL
  • Review error logs in agent dashboard

Next Steps​

Was this page helpful?