Secoda Analysis MCP Server

A read-only Model Context Protocol (MCP) server for exploring and analysing your Secoda data catalog. Designed for business users who need to discover data, look up metric definitions, and understand data lineage — without any risk of modifying the catalog.

Features

• Zero write access — completely safe to use; nothing in Secoda can be changed
• AI chat — ask Secoda's AI natural language questions about your data
• Semantic search — find tables, columns, dashboards, and documentation by keyword
• Glossary & definitions — browse business term definitions
• Data lineage — trace where data comes from and where it flows downstream
• Browse collections & Q&A — explore organised resource groups and previously answered questions

Tools

Tool	Purpose
ai_chat	Ask Secoda AI a natural language question (supports multi-turn conversations)
search_data_assets	Find tables, columns, charts, and dashboards by keyword
search_documentation	Find docs, glossary terms, and Q&A by keyword
retrieve_entity	Get full details of any entity by its Secoda ID
get_resource	Get full details of a catalog resource (table, column, view) by ID
list_resources	Browse and filter resources using structured criteria
entity_lineage	Trace upstream/downstream data flow for any entity
glossary	Browse all business term definitions in the workspace
list_collections	Browse organised groups of resources
get_collection	Get details of a specific collection
list_questions	Browse previously asked and answered Q&A threads
get_question	Read a specific question and its answer

Requirements

• Python 3.10+
• A Secoda account with API access
• A Secoda API token (read permissions are sufficient)

Setup

1. Get your Secoda API token

Generate a token at Secoda → Settings → API. Read permissions are sufficient.

2. Install with uvx (recommended)

No manual install needed — your MCP client runs the server automatically via uvx.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "secoda-analysis": {
      "command": "uvx",
      "args": ["secoda-analysis-mcp"],
      "env": {
        "API_TOKEN": "your-secoda-api-token"
      }
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "secoda-analysis": {
      "command": "uvx",
      "args": ["secoda-analysis-mcp"],
      "env": {
        "API_TOKEN": "your-secoda-api-token"
      }
    }
  }
}

3. Alternative: pip install

pip install secoda-analysis-mcp

Then replace the uvx block above with "command": "secoda-analysis-mcp" and "args": [].

4. Claude Desktop bundle (.mcpb) — for organisation-wide distribution

A .mcpb (MCP Bundle) is a ZIP archive that Claude Desktop installs via drag-and-drop — no manual config editing required. The bundle auto-installs all Python dependencies on first run; the only prerequisite is Python 3.9+.

Two manifests live in bundle/:

File	Purpose	Git
manifest.template.json	Generic — prompts the user for credentials at install time via Claude's UI	Committed
manifest.json	Org-specific — credentials hardcoded for silent deployment	Gitignored — never commit

Building an org bundle:

# 1. Create your org manifest (one-time setup)
cp bundle/manifest.template.json bundle/manifest.json

Edit bundle/manifest.json and set your values in mcp_config.env:

"env": {
  "API_TOKEN": "your-secoda-api-token",
  "API_URL": "https://your-org.secoda.co/api/v1/",
  "AI_PERSONA_ID": "your-persona-uuid"
}

AI_PERSONA_ID is optional — omit it to use the workspace default persona.

# 2. Build the bundle
chmod +x bundle/build.sh
./bundle/build.sh
# → dist/miinto-secoda-analyst.mcpb  (gitignored)

Distributing: Share dist/*.mcpb with colleagues. They drag-and-drop it onto Claude Desktop → Settings → Developer. Works on macOS and Windows.

Security: bundle/manifest.json and dist/ are both gitignored. Only the credential-free template is committed. Never add credentials to any file tracked by git.

Configuration

Variable	Description	Default
API_TOKEN	Your Secoda API token (required)	—
API_URL	Secoda API base URL	https://app.secoda.co/api/v1/
AI_PERSONA_ID	Secoda AI persona ID — pins a specific persona for all ai_chat calls. Find it in Secoda → Settings → AI → Personas.	workspace default

Example workflows

Ask a business question

ai_chat(prompt="How is Gross Margin calculated and what tables does it use?")

Find a table and explore its schema

# 1. Find the table
search_data_assets(query="order lines")

# 2. Get full details (columns, description, tags)
get_resource(resource_id="<id-from-search>", truncate_length=None)

Understand data lineage

# Find the entity first
search_data_assets(query="my_important_table")

# Then trace its lineage
entity_lineage(entity_id="<id-from-search>")

License

Apache License 2.0 — see LICENSE for details.

---

Development

Setup

Clone the repo and install all dependencies (including dev tools) with uv:

git clone https://github.com/mbrummerstedt/secoda-analysis-mcp.git
cd secoda-analysis-mcp
uv sync --extra dev

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Project structure

secoda-analysis-mcp/
├── src/
│   └── secoda_analysis/        # Main package
│       ├── __init__.py
│       ├── __main__.py         # python -m secoda_analysis entrypoint
│       ├── server.py           # FastMCP server setup and tool registration
│       ├── prompt.py           # MCP system prompt (tool guidance for the LLM)
│       ├── core/
│       │   ├── client.py       # HTTP client with retry logic
│       │   ├── config.py       # Environment variable configuration
│       │   └── models.py       # Pydantic models (filter/sort validation)
│       └── tools/
│           ├── ai_chat.py      # AI chat tool (submit + poll)
│           ├── collections.py  # list_collections, get_collection
│           ├── entity.py       # retrieve_entity, entity_lineage, glossary
│           ├── questions.py    # list_questions, get_question
│           ├── resources.py    # list_resources, get_resource
│           └── search.py       # search_data_assets, search_documentation
├── tests/
│   ├── conftest.py             # Root fixtures (env var defaults)
│   ├── mock/                   # Unit tests — all HTTP calls mocked
│   │   ├── conftest.py         # Shared mock fixtures and response payloads
│   │   ├── test_client.py
│   │   ├── test_models.py
│   │   ├── test_prompt.py
│   │   ├── test_tools_ai_chat.py
│   │   ├── test_tools_collections.py
│   │   ├── test_tools_entity.py
│   │   ├── test_tools_questions.py
│   │   ├── test_tools_resources.py
│   │   └── test_tools_search.py
│   └── integration/            # Integration tests — hit the real Secoda API
│       ├── conftest.py         # Auto-skip when API_TOKEN is not set
│       ├── test_ai_chat.py
│       ├── test_collections.py
│       ├── test_entity.py
│       ├── test_questions.py
│       ├── test_resources.py
│       └── test_search.py
├── pyproject.toml
├── .env.example
└── .python-version

Architecture

LLM / MCP client
      │  MCP protocol (stdio)
      ▼
  server.py  ──── registers tools from tools/*.py
      │
      ├── tools calling Secoda AI MCP endpoint
      │     tools/search.py, entity.py
      │           │
      │           └── core/client.py  call_tool()
      │                     │
      │                     └── POST {API_URL}/ai/mcp/tools/call/
      │
      ├── tools making direct REST calls
      │     tools/resources.py, collections.py, questions.py
      │           │
      │           └── core/client.py  _make_request_with_retry()
      │                     │
      │                     └── GET {API_URL}/resource/... etc.
      │
      └── ai_chat tool (submit + poll)
            tools/ai_chat.py
                  │
                  └── POST/GET {base_url}/ai/embedded_prompt/

All tools are read-only — there are no write, update, or delete operations.

Running tests

Mock tests (no credentials required, fast):

uv run pytest tests/mock/ -v

Integration tests (requires a valid API_TOKEN in your .env):

uv run pytest tests/integration/ -v

Integration tests hit the live Secoda API. The ai_chat tests are slow (30–120s each) as they wait for the AI to respond.

All tests:

uv run pytest -v

Integration tests are automatically skipped when API_TOKEN is not set.

Code style

This project uses Ruff for linting and formatting, and mypy for type checking.

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run mypy src/