# The-Snip MCP server — give this file to your AI assistant

Paste this file into your assistant's context — CLAUDE.md, project instructions, or
a system prompt — so it knows how to reach and use your team's The-Snip base over
MCP. A human does the one-time setup below; everything after that is for the agent.

## What this connects you to

The-Snip (https://the-snip.com) is a searchable, human-reviewed team knowledge base
of code snippets, saved API calls and Markdown docs. Approved items are trusted
canon — a human reviewed each one before it became part of the base. Search it
before solving a problem the team may have solved already, and file new knowledge
back so the base stays current.

## The endpoint

    https://the-snip.com/mcp

Streamable HTTP (MCP spec 2025-03-26+), POST-only. A GET returns 405 — that means
the client is on the old SSE transport; switch it to Streamable HTTP. Authenticate
with a workspace API key in the Authorization header:

    Authorization: Bearer snip_YOUR_WORKSPACE_KEY

## Setup (one-time, a human does this)

1. Create a workspace at https://the-snip.com — free, no card.
2. Open Settings → API keys in the app and generate a key. It starts with snip_
   and is shown exactly once.
   Reads are free — any agent can search the base on the Free plan. Agent writes (create and update) need Pro & Team, $8/user/mo.
3. Add the server to your MCP client. Generic config (Claude Code .mcp.json /
   Cursor .cursor/mcp.json):

    {
      "mcpServers": {
        "the-snip": {
          "url": "https://the-snip.com/mcp",
          "headers": { "Authorization": "Bearer snip_YOUR_WORKSPACE_KEY" }
        }
      }
    }

   Claude Code is one command:

    claude mcp add --transport http the-snip https://the-snip.com/mcp \
      --header "Authorization: Bearer snip_YOUR_WORKSPACE_KEY"

   ChatGPT and claude.ai connect over OAuth instead: add a custom connector
   pointed at https://the-snip.com/mcp and approve it in the browser — no key to
   paste. Per-client config syntax (VS Code, Codex CLI, Gemini CLI, Cline,
   Windsurf, Zed and more): https://the-snip.com/docs/mcp

Once connected, eight tools appear automatically. Verify the connection by asking
the agent to search the base — a search_base tool call should fire.

## The eight tools — and when to use them

### search_base — search the base (use this first, and often)

ALWAYS search the base before solving a problem the team may have solved already.
An empty query returns the most recent items. Results are scoped to your key's
workspace.

    { "query"?: string, "type"?: "snippet"|"api"|"doc", "language"?: string,
      "collectionId"?: string, "tags"?: string[],
      "sort"?: "relevance"|"updated"|"created"|"title", "limit"?: integer }

### get_item — fetch one item in full by id

Use when you have an id from search_base results and need the full item. Never
guess ids — an id outside your workspace returns 404. Free on every plan.

    { "id": string }

### list_collections — list the workspace's collections

Returns id and name rows. Check before filing: pass a real collectionId to
create_* or update_item so items land where the team expects them — never guess
collection ids. Free on every plan.

    {}

### create_snippet — file reusable code

Use when you wrote or fixed a piece of reusable code worth keeping: a hook, a helper,
a config block, a fix the team will hit again.

    { "title": string, "language": string, "code": string,
      "description"?: string, "collectionId"?: string, "sampleOutput"?: string }

### create_api — file a working API call

Use when you have a working API request worth saving — the method, URL, headers and
body that actually worked.

    { "title": string, "method": string, "url": string, "description"?: string,
      "collectionId"?: string, "headers"?: object, "requestBody"?: string,
      "sampleResponse"?: string }

### create_doc — file how-to or architecture knowledge

Use for knowledge that is prose rather than code: runbooks, how-tos, architecture
notes. The body is Markdown; [[wikilinks]] to other docs in the workspace are
supported.

    { "title": string, "body": string, "description"?: string, "collectionId"?: string }

### update_item — correct or extend an existing item

Use when a search result is outdated or incomplete. Patch by id — take ids from
search_base results, never guess them.

    { "id": string, ...any create fields, all optional }

### create_collection — create a collection to organize items

Use when no existing collection fits — check list_collections first and do not
create near-duplicates. Collections are organizational metadata: they do not enter
review and do not count against the item cap. Returns the new collection including
its id, ready to use as collectionId.

    { "name": string, "description"?: string }

To file items into collections: call list_collections, pass collectionId to
create_snippet / create_api / create_doc; update_item with collectionId moves an
existing item.

## The review contract (IMPORTANT)

Every item write you make — create or update — lands with status "in review". A human
approves it before it becomes canon. You CANNOT set the status yourself: the input
schemas reject unknown fields, so a smuggled status field comes back as a 400. Do not
re-submit an item because it is still in review — that is expected, not an error.
(create_collection is the exception: collections do not enter review.)

## Error handling

- 401 — missing or invalid key. Send the key as Authorization: Bearer snip_... and
  ask the human to check it in Settings → API keys (revoked or mistyped keys 401).
- 403 on a write — the message is: Agent writes need the Pro & Team plan — reads are free. Upgrade at https://the-snip.com/upgrade
  Reads never need the paid plan; ask the human to upgrade to enable writes. (On
  Free, the 25-item cap can also 403.)
- 404 on get_item or update_item — the id is not visible in your workspace. Search
  again with search_base and use an id from the results; never guess ids.
- 405 on GET /mcp — the endpoint is POST-only (Streamable HTTP). Configure your
  client for the Streamable HTTP transport, not SSE.
- 429 — rate limited (60 requests/min per workspace). Back off and retry after the
  indicated delay.