How do I use secoda-analysis-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@secoda-analysis-mcp How is Gross Margin calculated?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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/

secoda-analysis-mcp

Secoda Analysis MCP Server

Features

Tools

Requirements

Setup

1. Get your Secoda API token

2. Install with uvx (recommended)

3. Alternative: pip install

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

Configuration

Example workflows

Ask a business question

Find a table and explore its schema

Understand data lineage

License

Development

Setup

Project structure

Architecture

Running tests

Code style

Maintenance

Resources

Tools

Latest Blog Posts

MCP directory API