# Hindsight Sets a New Standard: #1 on the BEAM Benchmark

Claude Code recently added support for MCP agents, and it turns out to be a great match for Vectorize. If you work in the terminal, this is an easy way to give Claude real-time access to your internal docs, changelogs, specs, and more—without leaving the shell.

## Why Connect Claude Code to Your Vectorize Agent?

Imagine you’re deep in your terminal, debugging or writing code, and need to reference internal documentation fast. With Claude Code hooked up to your Vectorize agent, you’ll be able to get answers that are specific to your actual content—right from your docs.

Here are a couple of concrete examples:

### Filtering by content categories
Suppose you tag doc types such as `design doc`, `API spec`, or `architecture overview`. Claude can limit its search to that category, reducing noise and giving you the right answer faster.

### Querying recent updates or specs
If your internal documents include metadata like `document type: changelog` or `last updated: July 2025`, Claude Code can filter to only return the most relevant entries.

## What You’ll Need

- A **Vectorize pipeline** with your documents already indexed
- A **Claude Code** installation ([Download Claude](https://claude.ai/download))
- An **MCP Agent** in Vectorize connected to your pipeline
- An **Agent API Key** for secure access

## Step 1: Create an MCP Agent

1. Go to the **Agents** section in Vectorize
2. Click **New Agent**
3. Configure the following:
   - **Name**: e.g., “Claude Assistant”
   - **Type**: MCP Agent
   - **Pipeline**: Choose your existing pipeline
4. Set a system prompt:

`You are an engineering assistant with access to internal documentation. Always cite sources and provide code examples when relevant.`
5. Click **Create**, then copy the **Agent ID**

## Step 2: Add MCP Tools

Your agent needs at least one tool to function. You can create targeted tools that focus on specific document types, or a general search tool.

1. Go to **MCP Functions** in the sidebar
2. Create a new function (e.g., `search-docs` for general search, or `search-api-docs` for API-specific)
3. Add a clear description so Claude knows when to use it
4. (Optional) Add metadata filters if you want to narrow results (e.g., `document_type: api-spec`)
5. Assign the tool to your MCP Agent

**Tip**: Configure automatic metadata extraction schemas in your organization’s Metadata Schemas section to automatically extract document type, dates, and other structured information—no manual tagging needed.

## Step 3: Generate an API Key

1. In your agent settings, go to **Agent API Keys**
2. Click **New Key**, name it (e.g., “Claude Code”)
3. Copy the key immediately—you won’t be able to view it again

## Step 4: Connect Claude with One Command

Run this in your terminal (with your API key and Agent ID):

```bash
claude mcp add vectorize-mcp \
  --env VECTORIZE_API_KEY=YOUR_API_KEY \
  -- npx -y mcp-remote@latest https://agents.vectorize.io/api/agents/YOUR_AGENT_ID/mcp \
  --header "Authorization: Bearer ${VECTORIZE_API_KEY}"
```

(Replace the ID and key with your own — Claude will save them.)

Confirm it worked:

```bash
claude mcp list
```

## Example: Uploading with Metadata

While automatic metadata extraction handles most cases, here’s how to manually upload with custom metadata using the Python client:

```python
import json
import os
import time
import urllib3
import vectorize_client as v

# Initialize API client (assumes apiClient is configured)
# Create API instances
connectors_api = v.SourceConnectorsApi(apiClient)
uploads_api = v.UploadsApi(apiClient)

# Step 1: Create a file upload connector
file_upload = v.FileUpload(
    name=f"upload-for-claude-{int(time.time())}",
    type="FILE_UPLOAD",
    config={}
)

request = v.CreateSourceConnectorRequest(file_upload)
connector_response = connectors_api.create_source_connector(organization_id, request)
source_id = connector_response.connector.id

print(f"Created connector: {source_id}")

# Step 2: Upload a file with metadata
file_name = os.path.basename(file_path)
metadata = {"team": "backend", "feature": "auth-service"}

# Get upload URL
upload_request = v.StartFileUploadToConnectorRequest(
    name=file_name,
    content_type=content_type,
    metadata=json.dumps(metadata)  # Metadata as JSON string
)

start_response = uploads_api.start_file_upload_to_connector(
    organization_id,
    source_id,
    start_file_upload_to_connector_request=upload_request
)

# Upload file to presigned URL
http = urllib3.PoolManager()
with open(file_path, "rb") as f:
    response = http.request(
        "PUT",
        start_response.upload_url,
        body=f,
        headers={
            "Content-Type": content_type,
            "Content-Length": str(os.path.getsize(file_path))
        }
    )

if response.status == 200:
    print(f"Uploaded {file_name} with metadata: {metadata}")
else:
    print(f"Upload failed with status {response.status}")
```

## Use Cases

This setup is particularly helpful for:

- **Onboarding**: Let new engineers ask Claude about internal standards and architecture
- **Debugging**: Ask about tools, errors, or processes documented internally
- **Working with APIs**: Ask for request/response formats and find usage examples quickly

## Troubleshooting

- **Agent not responding?** Make sure your pipeline has finished processing.
- **Getting no results?** Check your document filters or wait for ingestion to complete.
- **Need to rotate keys?**

```bash
claude mcp remove vectorize-mcp
claude mcp add vectorize-mcp --env VECTORIZE_API_KEY=NEW_KEY ...
```

---

---