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.

Overview​

The complete MCP agent setup flow:

  1. Create an MCP agent - Set up the agent container
  2. Create tools - Define what the agent can do
  3. Generate API keys - Secure access credentials
  4. Connect to AI tools - Configure Claude Desktop, Cursor, etc.

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 tools to be useful.

Step 2: Create Agent Tools​

Your MCP agent needs tools to interact with your pipelines. Tools determine what capabilities your agent exposes to AI assistants.

Create Your First Tool​

  1. On your agent's detail page, click Create New Tool
  2. Follow the tool creation process

For detailed instructions on creating and configuring tools, see Creating Agent Tools.

Key Points for MCP Tools​

  • Tools are created the same way for all agent types
  • Each tool connects to a specific pipeline
  • Tools automatically appear in connected AI assistants
  • You can create multiple tools for different purposes

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 tool
  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 Tools​

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

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

Update Tools​

To modify what your agent can do:

  1. On your agent's detail page, view your existing tools
  2. Click Create New Tool to add more capabilities
  3. Edit or remove existing tools as needed
  4. Changes take effect immediately

Monitor Usage​

Track how your MCP agent is being used:

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

Best Practices​

Tool Design​

  • Clear Names: Use descriptive, action-oriented names
  • Detailed Descriptions: Help the AI understand when to use each tool
  • Focused Purpose: Each tool 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 tools
  • Monitor Access: Review usage logs regularly
  • Test Thoroughly: Verify tools return appropriate data

Performance​

  • Optimize Pipelines: Ensure underlying pipelines are fast
  • Use Filters: Configure tools 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 tool

No Results Returned​

  • Confirm pipeline has indexed documents
  • Check tool 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?