MCP Server - SkillDiscs

SkillDiscs exposes a production Model Context Protocol (MCP) server for read-only access to your API-visible Disks. Use MCP when your agent client already supports remote tools. Use the REST API when you are building your own app, backend job, workflow, or integration.

Endpoint

https://skilldiscs.com/api/mcp

The endpoint uses Streamable HTTP transport. In MCP client configuration, use type: "http" or transport: "http" depending on the client.

Authentication

Send your SkillDiscs API key as a bearer token:

Authorization: Bearer sk_your_key_here

Generate keys in Settings -> API Keys.

Treat MCP API keys like passwords. Anyone holding the key can query API-visible data from your SkillDiscs library.

Quick Setup

Claude Code

Claude Code can connect directly to remote HTTP MCP servers.

claude mcp add --transport http skilldiscs https://skilldiscs.com/api/mcp \
  --header "Authorization: Bearer sk_your_key_here"

Then verify the connection inside Claude Code:

/mcp

JSON MCP Config

Use this shape for clients that read .mcp.json, ~/.claude.json, or a similar MCP config file:

{
  "mcpServers": {
    "skilldiscs": {
      "type": "http",
      "url": "https://skilldiscs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SKILLDISCS_API_KEY}"
      }
    }
  }
}

Store the key in your environment instead of committing it:

export SKILLDISCS_API_KEY="sk_your_key_here"

Claude Agent SDK

When using an SDK that accepts MCP servers programmatically, pass the same HTTP endpoint and authorization header:

const mcpServers = {
  skilldiscs: {
    type: "http",
    url: "https://skilldiscs.com/api/mcp",
    headers: {
      Authorization: `Bearer ${process.env.SKILLDISCS_API_KEY}`,
    },
  },
}

If your client asks for allowed tool names, SkillDiscs tools follow the standard MCP naming pattern:

mcp__skilldiscs__list_topics
mcp__skilldiscs__browse_topic
mcp__skilldiscs__search_knowledge
mcp__skilldiscs__get_disk
mcp__skilldiscs__list_disks

Tools

Tool	Purpose
`list_topics`	Map of the topics in the library, with counts and subtopics
`browse_topic`	Disks under one plain-language topic, plus neighbouring subtopics
`search_knowledge`	Semantic search across your owned Disk sections
`get_disk`	Read one Disk by UUID or `public_id`
`list_disks`	Flat inventory listing by scope, exact category or exact tag

All tools return MCP text content whose text value is formatted JSON.

Discovery ladder

An agent with no screen — a voice agent especially — cannot start with search_knowledge, because it does not yet know what the library contains. The three discovery tiers are meant to be walked in order:

"What do you know about?"           → list_topics
"Tell me about quantum physics"     → browse_topic { topic: "quantum physics" }
"Why do entangled particles ...?"   → search_knowledge / get_disk

list_topics and browse_topic are both plain indexed reads over data that already exists (categories, AI tags, concept labels). Neither makes an AI call. browse_topic only pays for an embedding when the topic matches nothing lexically, so the common path stays fast enough for a spoken turn.

`list_topics`

The broad map of the library. Call this before anything else when the user asks what is available.

Input

Field	Type	Required	Notes
`language`	enum	No	`en` (default), `de`, `fr`, `es`. Affects topic labels only — subtopics keep the language they were generated in.

Output

{
  "library_size": 42,
  "topic_count": 6,
  "content_languages": ["de", "en"],
  "topics": [
    {
      "topic": "science",
      "label": "Science",
      "disk_count": 11,
      "subtopics": ["quantum physics", "entanglement", "thermodynamics"],
      "example_titles": ["Quantum Entanglement Explained", "Entropy From Scratch"]
    }
  ],
  "top_subtopics": [{ "name": "quantum physics", "disk_count": 4 }],
  "next_step": "Call browse_topic with any topic label or subtopic name to get the Disks in it."
}

topic is the stable category id (use it for list_disks.category); label is the display string. subtopics are the AI tags that occur most often inside that topic — these are the specific names an agent can say out loud. Disks whose original was deleted by their owner are excluded: they are placeholders with no title, category or content.

`browse_topic`

Resolve one plain-language topic name to the Disks about it. Resolution is tiered, and the tier used is reported in resolved_as:

`resolved_as`	How it matched
`category`	The term is one of the fixed category labels, in any supported language (“Psychologie” → `psychology`)
`keyword`	Whole-word match against tags, titles, summaries or extracted concept labels
`semantic`	Nothing matched lexically, so the term was embedded and matched against section content
`no_match`	Nothing in the library covers it — `available_topics` is returned instead

Input

Field	Type	Required	Notes
`topic`	string	Yes	Topic, category or subtopic name, in any supported language.
`limit`	integer	No	Defaults to `10`. Maximum `50`.

Output

{
  "topic": "quantum physics",
  "resolved_as": "keyword",
  "total": 2,
  "truncated": false,
  "disks": [
    {
      "public_id": "dk_9f2c1a",
      "title": "Quantum Entanglement Explained",
      "summary": "How entangled particles behave …",
      "category": "science",
      "tags": ["quantum physics", "entanglement"],
      "relationship": "owned",
      "word_count": 4200,
      "matched_on": ["tag:quantum physics", "title"]
    }
  ],
  "related_subtopics": [{ "name": "entanglement", "disk_count": 1 }],
  "next_step": "Call get_disk with a public_id to read a Disk, or search_knowledge to ask a question about it."
}

matched_on says why each Disk is in the list, so an agent can justify the answer instead of asserting relevance. related_subtopics are the sibling tags of the matched set with the query term removed — the next thing to offer when the user wants to narrow down. browse_topic returns metadata only. It never returns source text, so it is safe to call on any Disk regardless of visibility. title and summary are returned as plain speakable text: markdown syntax is stripped (link text is kept, the URL dropped) and the hard line breaks that Disk titles carry for card layout are collapsed. Accents and umlauts are left untouched. The same applies to example_titles in list_topics. A voice agent can read these fields aloud without any cleanup pass.

`search_knowledge`

Semantic search over owned Disk sections.

Input

Field	Type	Required	Notes
`query`	string	Yes	Search query. The server embeds the first 1,000 characters.
`limit`	integer	No	Defaults to `5`. Maximum `25`.

{
  "query": "how does spaced repetition work?",
  "limit": 5
}

Output

The tool returns a JSON array of search hits.

[
  {
    "disk_public_id": "abc123",
    "disk_title": "Memory Systems",
    "section_index": 3,
    "similarity": 0.91,
    "key_points": ["Reviews should happen before forgetting"],
    "redacted": false,
    "section_text": "..."
  }
]

For redacted hits, use snippet instead of section_text:

[
  {
    "disk_public_id": "def456",
    "disk_title": "Public Learning Notes",
    "section_index": 2,
    "similarity": 0.84,
    "key_points": ["Retrieval strengthens memory"],
    "redacted": true,
    "snippet": "..."
  }
]

Search is currently scoped to owned Disks. Saved Disks can be listed with list_disks and read with get_disk, but semantic search results come from the authenticated user’s own indexed sections.

`get_disk`

Read one Disk by UUID or public_id.

Input

Field	Type	Required	Notes
`disk_id`	string	Yes	Disk UUID or public ID.

{
  "disk_id": "abc123"
}

Output

The tool returns one Disk object.

{
  "public_id": "abc123",
  "title": "Memory Systems",
  "summary": "...",
  "category": "Learning",
  "word_count": 1240,
  "visibility": "private",
  "relationship": "owned",
  "source_url": "https://example.com/source",
  "ai_generated": true,
  "redacted": false,
  "tags": ["learning", "memory"],
  "sections": [
    {
      "index": 1,
      "word_count": 180,
      "key_points": ["..."],
      "text": "..."
    }
  ],
  "related_disks": [
    {
      "public_id": "rel789",
      "title": "Forgetting Curves",
      "similarity": 0.76
    }
  ],
  "text": "...",
  "created_at": "2026-06-06T12:00:00.000Z"
}

Full text and sections[].text are conditional:

Access	`redacted`	Source text fields
Owner viewing own private Disk	`false`	`text` and `sections[].text` can be present
Owner viewing own published Disk	`true`	Full source text is omitted
Active saved Disk from another owner	`true`	Full source text is omitted

If the Disk is not accessible to the API key, the tool returns JSON text like:

{
  "error": "not_found",
  "message": "Disk not found"
}

`list_disks`

List Disks available to the authenticated API key.

Input

Field	Type	Required	Notes
`scope`	string	No	`all`, `owned`, `saved`, `private`, or `published`. Defaults to `all`.
`category`	string	No	Exact category name.
`tag`	string	No	Exact tag name.
`limit`	integer	No	Defaults to `20`. Maximum `100`.

{
  "scope": "all",
  "limit": 20
}

Output

The tool returns a list response:

{
  "scope": "all",
  "total": 1,
  "disks": [
    {
      "public_id": "abc123",
      "title": "Memory Systems",
      "summary": "...",
      "category": "Learning",
      "visibility": "private",
      "relationship": "owned",
      "owner_user_id": "8fb1d0c2-08d1-46ef-a2f3-6bf241745e24",
      "owner_display_name": "SkillDiscs User",
      "word_count": 1240,
      "tags": ["learning"],
      "saved_at": null,
      "created_at": "2026-06-06T12:00:00.000Z"
    }
  ]
}

Scope behavior:

Scope	Includes
`all`	Owned Disks plus active saved Disks
`owned`	Disks created by the authenticated user
`saved`	Active saved Disks from other owners
`private`	Owned unpublished Disks
`published`	Owned published Disks

Redaction

MCP uses the same redaction policy as the REST API:

Owner-private Disk access can include full source text.
Owner-published and saved Disk access returns redacted, AI-derived fields.
Search hits include either section_text or snippet.

Always check redacted before assuming verbatim source text is present.

Errors

Authentication and rate-limit errors are returned by the HTTP endpoint before MCP tool execution.

HTTP status	Error	Meaning
`401`	`unauthorized`	Missing or invalid API key
`403`	`plan_upgrade_required`	MCP access requires Scholar or Pro
`429`	`rate_limit_exceeded`	Request limit exceeded
`500`	`internal_error`	Server error or upstream lookup failure

Best Practices

Start with list_topics when the agent has no idea what the library contains — do not guess a search query.
Use browse_topic when the user names a subject; use search_knowledge when the user asks a question.
Use get_disk when the agent already has a Disk UUID or public ID.
Use list_disks for inventory questions (counts, what is still private), not for subject exploration.
For voice agents: list_topics → browse_topic are the two calls cheap enough to run inside a spoken turn. Defer search_knowledge until the user has picked a Disk or asked a real question.
Treat all returned content as user-scoped and private to the API key holder.
Check redacted and prefer section_text ?? snippet in agent prompts.

​Endpoint

​Authentication

​Quick Setup

​Claude Code

​JSON MCP Config

​Claude Agent SDK

​Tools

​Discovery ladder

​list_topics

​Input

​Output

​browse_topic

​Input

​Output

​search_knowledge

​Input

​Output

​get_disk

​Input

​Output

​list_disks

​Input

​Output

​Redaction

​Errors

​Best Practices

Endpoint

Authentication

Quick Setup

Claude Code

JSON MCP Config

Claude Agent SDK

Tools

Discovery ladder

`list_topics`

Input

Output

`browse_topic`

Input

Output

`search_knowledge`

Input

Output

`get_disk`

Input

Output

`list_disks`

Input

Output

Redaction

Errors

Best Practices