Setup Guide

Ballast exposes each collection as a Model Context Protocol (MCP) server. Claude Desktop can connect to these servers to search your indexed data, query databases, and create visualizations directly during conversations.

Prerequisites

• Claude Desktop installed
• A Ballast collection with at least one connected source
• A collection API key (created in the Ballast dashboard)

How It Works

Unlike traditional MCP servers that run as separate processes, Ballast serves MCP endpoints directly via HTTP at:

https://api.ballast.sh/mcp/collections/{collection-readable-id}

Each collection gets its own MCP server with tools scoped to that collection’s data.

Step 1: Create an API Key

1. Open your collection in the Ballast dashboard
2. Go to Settings → API Keys
3. Click Create API Key
4. Name it (e.g., “Claude Desktop”)
5. Copy the key—it starts with bk_ and is shown only once

Step 2: Get Your Collection’s Readable ID

Find your collection’s readable ID in Settings → General. This is the URL-friendly identifier (e.g., engineering-docs, company-knowledge).

Step 3: Configure Claude Desktop

Open Claude Desktop’s configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%Claudeclaude_desktop_config.json

Add your Ballast collection:

{
  "mcpServers": {
    "ballast-your-collection": {
      "url": "https://api.ballast.sh/mcp/collections/your-collection-id",
      "headers": {
        "Authorization": "Bearer bk_your_api_key_here"
      }
    }
  }
}

Replace:

• your-collection-id with your collection’s readable ID
• bk_your_api_key_here with your API key

Step 4: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a hammer icon indicating MCP tools are available.

Available Tools

Ballast exposes different tools depending on your collection’s data sources:

For Document Collections

Collections with non-federated sources (Slack, Google Drive, Notion, etc.) expose:

Tool	Description
search	Semantic search with query expansion, reranking, and answer generation
list_documents	Browse indexed documents (metadata only, saves tokens)
read_document	Read a specific document’s content with pagination
list_sources	List connected data sources
trigger_sync	Trigger a data sync for a source
get_info	Get collection details
get_dashboard_conventions	Get industry-specific visualization best practices
create_chart	Create and save visualizations

For Database Collections

Collections with federated database sources (PostgreSQL, MySQL, etc.) expose:

Tool	Description
list_tables	List all tables in the database
describe_table	Get column names and types for a table
query_data	Execute read-only SQL queries
list_sources	List connected data sources
trigger_sync	Trigger a data sync
get_info	Get collection details
get_dashboard_conventions	Get industry-specific visualization best practices
create_chart	Create and save visualizations

Database queries are executed live—no syncing required.

Example Usage

Once configured, you can ask Claude naturally:

For document collections:

Search Ballast for our remote work policy

Find all Slack messages about the product launch

What did Sarah say about the Q3 roadmap?

For database collections:

Show me the tables in our database

Query the users table for signups in the last 30 days

Create a chart of monthly revenue from the orders table

Claude uses the appropriate Ballast tools automatically based on your question.

Multiple Collections

You can connect multiple collections by adding more entries to mcpServers:

{
  "mcpServers": {
    "ballast-engineering": {
      "url": "https://api.ballast.sh/mcp/collections/engineering-docs",
      "headers": {
        "Authorization": "Bearer bk_engineering_key"
      }
    },
    "ballast-sales": {
      "url": "https://api.ballast.sh/mcp/collections/sales-data",
      "headers": {
        "Authorization": "Bearer bk_sales_key"
      }
    }
  }
}

Search Tool Parameters

The search tool supports extensive parameters for fine-grained control:

Parameter	Type	Description
query	string	Search query (required)
limit	int	Max results (default: 10, max: 20)
offset	int	Pagination offset
search_type	string	semantic, keyword, or hybrid (default)
expand_query	bool	Generate query variations
rerank	bool	Apply LLM reranking
rerank_model	string	cohere or jina
generate_answer	bool	Synthesize answer from results
temporal_relevance	float	Recency weighting (0.0-1.0)
interpret_filters	bool	Extract filters from natural language
filters	object	Explicit metadata filters

Troubleshooting

No hammer icon in Claude

Verify your config file is valid JSON. Use a JSON validator if needed.

“Authentication required” error

Check that your API key:

• Starts with bk_
• Is included in the Authorization header with Bearer prefix
• Has not been revoked

“Collection not found” error

Verify the collection readable ID in your URL matches exactly what’s shown in your Ballast dashboard.

Empty search results

• Check that your sources have finished syncing (see Sources panel in dashboard)
• Try simpler queries first
• Use list_documents to see what’s indexed

Permission denied

Ensure your API key has access to this collection. Collection-scoped keys only work for the specific collection they were created for.

Security

• API keys are stored in your local Claude config file
• Keys are transmitted over HTTPS only
• Collection-scoped keys limit access to that collection’s data
• Search results appear in your Claude conversation—be mindful when sharing

Self-Hosting

Enterprise customers can run Ballast on their own infrastructure. The MCP endpoint works the same way—just point to your self-hosted URL instead of api.ballast.sh.