Skip to main content

MCP Tools Integration

This guide explains how tools work specifically with MCP (Model Context Protocol) agents and how they differ from other agent types.

How MCP Tools Work​

Unlike Chat agents that use direct API calls, MCP agents expose tools through the Model Context Protocol using JSON-RPC 2.0. This allows AI assistants like Claude Desktop, Cursor, and Claude Code to discover and use your tools automatically.

Tool Discovery​

When an MCP client connects to your agent:

  1. Authentication - The client authenticates using your API key
  2. Tool listing - The client calls tools/list to discover available tools
  3. Automatic UI - Tools appear in the assistant's interface
  4. Dynamic invocation - The assistant can call tools based on user queries

Protocol Communication​

MCP uses JSON-RPC 2.0 messages:

// Client requests available tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

// Agent responds with tool definitions
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search-docs",
        "description": "Search technical documentation",
        "inputSchema": {
          "type": "object",
          "properties": {
            "question": {
              "type": "string",
              "description": "The search query"
            }
          }
        }
      }
    ]
  }
}

Creating Tools for MCP Agents​

Tools are created the same way for all agent types through the Vectorize UI. See Creating Agent Tools for the complete guide.

The key difference is how tools are exposed and invoked - MCP agents automatically translate your tools into the MCP protocol format.

Tool Behavior in MCP Clients​

In Claude Desktop​

Your tools appear in the tool palette:

  • Tools are grouped under your agent name
  • The assistant sees tool descriptions and parameters
  • Results are displayed inline in the conversation
  • The assistant maintains context across tool calls

In Cursor​

Tools integrate with the IDE:

  • Available through the AI chat interface
  • Can analyze code context alongside your data
  • Results inform code suggestions
  • Useful for documentation-aware coding

In Claude Code​

Terminal-based interaction:

  • Tools accessible via command palette
  • Results displayed in terminal output
  • Ideal for CLI workflows
  • Supports piping and scripting

Testing MCP Tools​

Unlike Chat agents, MCP tools cannot be tested directly in the Vectorize UI. Instead:

1. Test with Claude Desktop​

# Configure your MCP server in Claude Desktop settings
{
  "mcpServers": {
    "your-agent": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", 
               "https://agents.vectorize.io/api/agents/YOUR_AGENT_ID/mcp"],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Then verify:

  1. Open Claude Desktop
  2. Check that your agent appears in the tools menu
  3. Try invoking a tool with a test query
  4. Verify results match expectations

2. Test with MCP Inspector​

For debugging, use the MCP Inspector tool:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Connect to your agent
mcp-inspector https://agents.vectorize.io/api/agents/YOUR_AGENT_ID/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

This shows:

  • Raw protocol messages
  • Tool invocation details
  • Response formatting
  • Error messages

3. Monitor in Vectorize Dashboard​

Track tool usage:

  • View invocation counts
  • Check error rates
  • Monitor response times
  • Review query patterns

MCP Protocol Details​

Authentication​

MCP agents require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

The API key must have appropriate permissions for the agent and its connected pipelines.

Connection Types​

MCP supports two connection methods:

  1. Server-Sent Events (SSE) - For streaming responses
  2. Standard HTTP - For request/response patterns

Most clients use SSE for real-time interaction.

Tool Input Schema​

Tools must define parameters using JSON Schema:

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The search query"
    },
    "k": {
      "type": "number",
      "description": "Number of results",
      "default": 10
    },
    "service_name": {
      "type": "string",
      "description": "Filter by service"
    }
  },
  "required": ["question"]
}

Standard Parameters​

All MCP tools automatically include:

  • question - The search query (required)
  • k - Result count (optional, default: 10)
  • rerank - Enable reranking (optional)
  • mode - Search mode for Vectorize DB (optional)

Troubleshooting​

Tools Not Appearing​

If tools don't show in your MCP client:

  1. Verify agent configuration

    • Agent must be type "MCP"
    • Agent must be active
    • Tools must be assigned to the agent

  2. Check authentication

    • API key is valid
    • Key has correct permissions
    • Authorization header is properly formatted

  3. Test connection

    curl https://agents.vectorize.io/api/agents/YOUR_AGENT_ID/mcp \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool Invocation Errors​

Common issues and solutions:

  • "Tool not found" - Verify tool name matches exactly
  • "Invalid parameters" - Check parameter types match schema
  • "Pipeline error" - Ensure pipeline has indexed content
  • "Authentication failed" - Refresh API key and reconnect

Performance Issues​

To optimize tool performance:

  1. Use specific tool names - Help the LLM choose correctly
  2. Write clear descriptions - Reduce ambiguous invocations
  3. Link parameters to metadata - Enable efficient filtering
  4. Monitor usage patterns - Identify optimization opportunities

Best Practices​

Tool Design for MCP​

  1. Clear naming - MCP clients show tool names directly
  2. Descriptive parameters - Help the LLM understand usage
  3. Appropriate defaults - Most MCP invocations use defaults
  4. Error messages - Return helpful context for debugging

Security Considerations​

  • API key rotation - Regularly refresh keys
  • Permission scoping - Limit keys to specific agents
  • Usage monitoring - Track unusual patterns
  • Rate limiting - MCP connections respect rate limits

What's Next?​

Was this page helpful?