Getting Started with the Solid MCP Server

What You Can Do

Once connected, you can:

• Build agentic workflows that query your data automatically as part of a larger AI pipeline
• Generate SQL from plain English — describe what you want and get the query back instantly
• Integrate Solid's data layer directly into the AI tools and agents you build
• Explore your data interactively — tables, columns, metrics, and more through conversation

How It Works

Understanding this flow will save you debugging time:

Your AI tool / agent
        ↓  (MCP protocol)
Solid MCP Server
        ↓  (semantic model lookup)
Your Solid semantic layer
        ↓  (SQL generation)
SQL query returned to your tool
        ↓  (you run this)
Your data warehouse (Snowflake, BigQuery, etc.)
        ↓
Results

Key point: Solid generates SQL. It does not query your warehouse directly, and it does not move or store your data. Your tool or agent runs the returned SQL against your warehouse using your existing credentials and connection.

This means:

• Solid only needs read access to your semantic layer metadata — not your raw data
• All warehouse-level permissions and access controls remain in effect
• You control where and how the SQL executes

Architecture & Security

Before You Start

You will need:

1. A data warehouse connection configured in Solid. The text2sql tool generates SQL for your specific warehouse schema. Ask your Solid admin to confirm your connection is active.

2. The Solid MCP Server URL:

   https://mcp.production.soliddata.io/mcp

3. A way to authenticate — browser sign-in (easiest, no token management) or a management key from your Solid admin (for automated/production use).

Which Setup Is Right for You?

Not sure? If you're a developer building an automated pipeline or agent, use Option B. If you're trying Solid out interactively in a coding assistant, use Option A.

Option A — Sign in with your browser

Best for: Cursor, Claude Desktop, Windsurf, and any MCP-compatible tool you use interactively.

No tokens to manage. The client handles auth automatically.

Cursor

1. Open Settings → MCP, or press Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows) and search MCP: Add Server.
2. Click + Add new MCP server and enter:
   • Name: Solid
   • Type: streamable-http
   • URL: https://mcp.production.soliddata.io/mcp
3. Save. On first use, Cursor opens a browser window — sign in with your Solid credentials.

Prefer config-as-code? Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "Solid": {
      "url": "https://mcp.production.soliddata.io/mcp",
      "transport": "streamable-http"
    }
  }
}

Claude Desktop, Windsurf, and other tools

Add a new MCP server with:

• URL: https://mcp.production.soliddata.io/mcp
• Transport: streamable-http

Sign in when prompted. Token refresh is handled automatically.

Option B — Use an access token

Best for: CrewAI, Workato, CI/CD pipelines, scripts, and any non-interactive environment.

Step 1 — Get a token

Ask your Solid admin for a management key, then exchange it for a JWT:

curl --location 'https://backend.production.soliddata.io/api/v1/auth/exchange_user_access_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "management_key": "YOUR_MANAGEMENT_KEY"
  }'

Response:

"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs..."

Token expiry: JWTs expire after 30 minutes. Build your application to refresh by calling the exchange endpoint again before expiry — every 25 minutes is a safe interval.

Best practice: Store your management key as an environment variable (e.g. SOLID_MANAGEMENT_KEY). Never hardcode it in source code.

Step 2 — Connect your tool

CrewAI:

import os
from crewai.tools import MCPServerHTTP
 
mcp_server = MCPServerHTTP(
    url="https://mcp.production.soliddata.io/mcp",
    headers={"Authorization": f"Bearer {os.environ['SOLID_MCP_TOKEN']}"},
    streamable=True,
    cache_tools_list=True,
)

Any HTTP-based tool:

Option C — Connect via Microsoft Copilot Studio

Best for: Copilot Studio agents running in Teams or other Microsoft channels.

Uses the native MCP onboarding wizard — no bridge or additional infrastructure needed.

Prerequisites

• A Solid management key from your admin
• Your Semantic layer ID(s) — the UUID(s) of your Solid semantic layer(s)
• Access to Microsoft Copilot Studio

Setup

1. In Copilot Studio, open your agent and go to Tools.
2. Select Add a tool → New tool → Model Context Protocol.
3. Enter:
   • Server name: Solid Text2SQL
   • Server description: Converts natural language questions to SQL using Solid's semantic layer
   • Server URL: https://mcp.production.soliddata.io/mcp
4. Choose authentication: API key or OAuth 2.0 depending on what your Solid admin provided.
5. Select Create, then Add to agent.

Configuring your agent

Once connected:

• Agent instructions: Tell the agent when to use Solid, e.g.: "For any data or analytics questions, use the Solid Text2SQL action to generate SQL."
• Web search: Consider disabling or limiting web search for data questions so the agent routes to Solid instead.
• Testing: Enable "Show activity map when testing" to confirm the tool is being called and SQL is returned.

Troubleshooting

Available Tools

text2sql

Describe what you want in plain English. The tool returns a SQL query you can run against your warehouse.

Parameters:

• question (required) — your natural language question
• source_system (optional) — your warehouse type, e.g. snowflake, big_query. If you have multiple connected sources and omit this, the tool will ask you to choose.

Examples:

Single data source:

"What were total sales last month?"

→ Returns SQL. Run it against your warehouse.

Multiple data sources:

"Show me top 10 customers by revenue."

→ If multiple sources are configured, returns a list of options. Reply with your choice (e.g. snowflake), then call again with source_system set.

What a good output looks like:

SELECT
    DATE_TRUNC('month', o.order_date) AS month,
    r.region_name,
    SUM(o.revenue) AS total_revenue
FROM edw.mart.orders o
JOIN edw.mart.regions r ON o.region_id = r.region_id
WHERE o.order_date >= DATEADD('month', -1, DATE_TRUNC('month', CURRENT_DATE))
  AND o.order_date < DATE_TRUNC('month', CURRENT_DATE)
GROUP BY 1, 2
ORDER BY 1, 3 DESC;

Solid uses your semantic layer to resolve the correct table names, join paths, and metric definitions — rather than guessing from column names alone.

glossary_search

Ask for a definition of a glossary term in plain English. The tool returns the glossary definition stored in Solid, and additional context.

Parameters:

• query (required) — your natural language question about a term meaning

Examples:

"What does LLS mean?"

What a good output looks like:

"LLS stands for Lens Loyalty Score. It quantifies a customer's purchase frequency of sunglasses from the brand. A higher LLS indicates a longer and more consistent relationship with the brand. As customers make more purchases and their LLS increases, they become eligible for greater benefits, such as special discounts, advance notice of new styles, and tailored promotions, which recognize their ongoing patronage. Additionally, a RayCatcher is a new customer who does not yet have a Lens Loyalty Score (LLS), while a ShadeShifter is a valued customer with multiple purchases, resulting in a higher LLS and access to exclusive perks and rewards. The LLS is therefore central to determining customer status and eligibility for rewards within the brand's loyalty program."

Debugging & Validation

SQL looks wrong or returns unexpected results?

Work through these in order:

1. Check the semantic layer ID — if you have multiple semantic layers, confirm you're pointing at the right one.
2. Be more specific in your question — vague questions produce vague SQL. Instead of "show me revenue", try "show me total revenue by region for Q1 2025".
3. Check your warehouse connection — confirm your DWH connection is active in the Solid UI. The MCP server cannot generate correct SQL if the schema metadata is stale or missing.
4. Inspect the returned SQL before running it — review table names and joins against your known schema before executing, especially in production.
5. Token expired? — If you're using Option B and getting 401 errors, your JWT has expired. Refresh it using the exchange endpoint.

If results are consistently wrong for a particular metric or table, the issue is likely in the semantic layer definition itself (missing join, incorrect metric logic, etc.) — contact your Solid admin to review the model.

Custom Headers

When using bearer token auth, you can attach custom headers to enrich Solid's MCP usage logs. Useful for tracing activity across agents and workflows.

Example (any HTTP tool):

{
  "Authorization": "Bearer <your-token>",
  "X-Solid-Client": "CrewAI",
  "X-Solid-Labels": "workflow=weekly_report, agent_type=researcher"
}

CrewAI example:

mcp_server = MCPServerHTTP(
    url="https://mcp.production.soliddata.io/mcp",
    headers={
        "Authorization": f"Bearer {os.environ['SOLID_MCP_TOKEN']}",
        "X-Solid-Client": "CrewAI",
        "X-Solid-Labels": "workflow=weekly_report,env=production,agent_type=researcher",
    },
    streamable=True,
    cache_tools_list=True,
)

Use X-Solid-Labels to tag by environment (env=production), workflow name, or agent role — whatever makes filtering in your Solid usage dashboard most useful.

Quick Reference