> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skilldiscs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, Claude Code, agent SDKs, and other MCP clients to your SkillDiscs library.

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

```text theme={null}
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:

```http theme={null}
Authorization: Bearer sk_your_key_here
```

Generate keys in [Settings -> API Keys](https://skilldiscs.com/settings).

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

## Quick Setup

### Claude Code

Claude Code can connect directly to remote HTTP MCP servers.

```bash theme={null}
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:

```text theme={null}
/mcp
```

### JSON MCP Config

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

```json theme={null}
{
  "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:

```bash theme={null}
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:

```ts theme={null}
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:

```text theme={null}
mcp__skilldiscs__search_knowledge
mcp__skilldiscs__get_disk
mcp__skilldiscs__list_disks
```

## Tools

| Tool               | Purpose                                         |
| ------------------ | ----------------------------------------------- |
| `search_knowledge` | Semantic search across your owned Disk sections |
| `get_disk`         | Read one Disk by UUID or `public_id`            |
| `list_disks`       | List owned and active-saved Disks               |

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

## `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`.                              |

```json theme={null}
{
  "query": "how does spaced repetition work?",
  "limit": 5
}
```

### Output

The tool returns a JSON array of search hits.

```json theme={null}
[
  {
    "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`:

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

<Note>
  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.
</Note>

## `get_disk`

Read one Disk by UUID or `public_id`.

### Input

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

```json theme={null}
{
  "disk_id": "abc123"
}
```

### Output

The tool returns one Disk object.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`.                                       |

```json theme={null}
{
  "scope": "all",
  "limit": 20
}
```

### Output

The tool returns a list response:

```json theme={null}
{
  "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              |
| `429`       | `rate_limit_exceeded` | Request limit exceeded                  |
| `500`       | `internal_error`      | Server error or upstream lookup failure |

## Best Practices

* Prefer `search_knowledge` when the agent has a question and does not know the relevant Disk.
* Use `list_disks` before `get_disk` when the agent needs to choose from the user's library.
* Use `get_disk` when the agent already has a Disk UUID or public ID.
* Treat all returned content as user-scoped and private to the API key holder.
* Check `redacted` and prefer `section_text ?? snippet` in agent prompts.