# Add MCP Skill

> Add a new BigQuery-backed skill to the MCP server: a tool exposed to AI agents plus the .md context files that describe the underlying data. Invoke when the user wants AI agents (claude.ai, Claude Code, Cursor) to query a new domain of the warehouse.

- Skill: `pol-cc/add-mcp-skill` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add pol-cc/add-mcp-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pol-cc/add-mcp-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: pol-cc (https://skillmd.com/u/pol-cc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pol-cc/add-mcp-skill

---


# add-mcp-skill

> **Status**: v0.10.0 — folder-pattern reference written (the most important component) and the runnable MCP server skeleton (`templates/mcp-skeleton/`) is now included (FastMCP `server.py` with read tools always-on and write tools **off by default**). **Write tools are safe-by-default: off unless `MCP_WRITE_TOOLS=on`, and when on they OPEN A PR for human review rather than pushing to `main`** (the server feeds untrusted synced data to an agent — see [`references/mcp-github-writeback.md`](references/mcp-github-writeback.md), "Security posture"). Docker/compose/deploy and a working `example-sales` skill ship too. Step-by-step playbook for adding a skill to an existing MCP server still skeletal.

## What this skill does

Extends the client's MCP server with a new "skill" — a callable tool plus its context. After this skill runs, an AI agent connected to the MCP server can answer natural-language questions about the new data domain, generate the right SQL, and execute it against BigQuery.

The pattern mirrors `pol-cc/skills-sapiens` (the reference MCP deployment): one MCP server, multiple skills, each scoped to a domain (sales, finance, marketing, etc.).

## Preflight

```bash
if [ ! -f .agentic-data-engineer.json ]; then
  echo "[abort] not a managed MDS deployment"
  exit 1
fi

jq -e '.stack.mcp == true' .agentic-data-engineer.json > /dev/null || {
  echo "[abort] this MDS doesn't have an MCP server"
  echo "run Phase 3 of create-mds first"
  exit 1
}
```

## Anatomy of an MCP skill

Each skill in the MCP server is a folder under `mcp-server/skills/<skill-name>/`:

```
<skill-name>/
├── descriptor.json    declares which BQ datasets/tables this skill can read
├── context.md         business context the LLM needs to write correct SQL
├── schema.md          per-table column documentation, gotchas, joins
└── examples.sql       example queries (the LLM learns the pattern)
```

The MCP server exposes one generic `run_bq_query` tool and uses the per-skill files as **the context** the calling agent loads before composing a query.

## Playbook outline

**Phase A — Define the skill scope**

Ask the user:

1. What domain? (sales, finance, marketing, operations, HR, etc.)
2. Which BigQuery tables/datasets are in scope?
3. What kinds of questions should the skill answer?

**Phase B — Write the skill files**

1. `descriptor.json` — declare allowed tables, max bytes per query, max rows.
2. `context.md` — business glossary: what is a "customer" in this client's world, how are channels classified, etc.
3. `schema.md` — for each table, the meaningful columns + gotchas (e.g. "amount is signed for refunds", "vendor_code is NULL for off-catalog").
4. `examples.sql` — three to five canonical queries the LLM can pattern-match against.

See [`templates/mcp-skeleton/`](templates/mcp-skeleton/) — a runnable starter (FastMCP `server.py`, `requirements.txt`, `Dockerfile`, `docker-compose.yml`, `.env.example`, `deploy.sh`) shipping with a working `skills/example-sales/` skill. Copy a sibling of `example-sales`, edit the four files for the new domain.

**Phase C — Deploy**

1. Commit the new skill folder to the client repo.
2. On the VPS, pull the change and restart the MCP container.
3. Verify the skill is listed via `list_skills()` from an MCP client.

**Phase D — Verify**

Connect to the MCP server from claude.ai or Claude Code and ask a representative question. Confirm the LLM produces correct SQL grounded in the context files.

## References

Folder pattern (complete):
- [`references/mcp-skill-folder-pattern.md`](references/mcp-skill-folder-pattern.md) — the four-file structure (descriptor.json + context.md + schema.md + examples.sql), quality bars per file, iteration loop, multi-skill rules

Background (in create-mds Phase 3):
- [`../create-mds/references/mcp-server-architecture.md`](../create-mds/references/mcp-server-architecture.md) — how the MCP server uses these files

Templates (complete):
- [`templates/mcp-skeleton/`](templates/mcp-skeleton/) — runnable MCP server starter: FastMCP `server.py` (always-on read tool + `list_skills`/`get_skill_context`, plus the two write tools that register **only when `MCP_WRITE_TOOLS=on`** and then **open a PR rather than push to `main`** — `_open_pr` branches, commits, pushes the branch, and calls the GitHub PR API; with the SELECT-only / table-allowlist / path-traversal / sync-before-write / branch-cleanup-on-failure safety logic), `requirements.txt`, `Dockerfile`, `docker-compose.yml`, `.env.example` (`MCP_WRITE_TOOLS=off` default), `deploy.sh`, `README.md`, and a working `skills/example-sales/` skill (descriptor.json + context.md + schema.md + examples.sql)

Still to be written:
- `references/skills-sapiens-reference.md` — annotated walkthrough of the production reference deployment's first skill