Skald Server

Chat with your Skald knowledge base, add and update new knowledge, and search through memos.

Features

The Skald MCP server provides seven powerful tools:

1. skald-chat

Ask Skald questions about your knowledge base in natural language with optional filters to narrow search context.

2. skald-search

Search through your memos using multiple methods with optional filters:

• Semantic search (chunk_vector_search) - Find relevant content by meaning
• Title contains (title_contains) - Case-insensitive substring matching
• Title starts with (title_startswith) - Case-insensitive prefix matching

3. skald-create-memo

Create new memos that are automatically processed, summarized, tagged, chunked, and indexed for search.

4. skald-get-memo

Retrieve a memo by UUID or client reference ID with full content, summary, tags, and chunks.

5. skald-update-memo

Update an existing memo by UUID or client reference ID. If content is updated, the memo will be reprocessed.

6. skald-delete-memo

Permanently delete a memo by UUID or client reference ID along with all associated data.

7. skald-generate

Generate documents based on prompts and retrieved context from the knowledge base with optional style/format rules and filters.

Setup

Prerequisites

1. A Skald account with an API key. Get yours at platform.useskald.com
2. Node.js 18.0.0 or higher

Installation

1. Clone this repository:

git clone https://github.com/skaldlabs/skald-mcp
cd skald-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Cursor

1. Open Cursor Settings (cmd+shift+p on macOS or ctrl+shift+p on Windows → "Cursor Settings")

2. Select "MCP" from the left sidebar and click "Add new global MCP server"

3. Add the following configuration:

{
  "mcpServers": {
    "skald": {
      "type": "command",
      "command": "node ABSOLUTE_PATH_TO_PROJECT/build/index.js --key=YOUR_SKALD_API_KEY"
    }
  }
}

Replace:

• ABSOLUTE_PATH_TO_PROJECT with the full path to your skald-mcp directory
• YOUR_SKALD_API_KEY with your Skald API key

Tip: Right-click on /build/index.js in Cursor and select "Copy Path" to get the absolute path.

Command-line arguments:

• --key: Your Skald API key (required if not using environment variable)

Claude Desktop

1. Open Claude Desktop settings and navigate to the "Developer" tab

2. Click "Edit Config"

3. Add the following configuration:

{
  "mcpServers": {
    "skald": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_PROJECT/build/index.js"
      ],
      "env": {
        "SKALD_API_KEY": "YOUR_SKALD_API_KEY"
      }
    }
  }
}

Replace:

• ABSOLUTE_PATH_TO_PROJECT with the full path to your skald-mcp directory
• YOUR_SKALD_API_KEY with your Skald API key

Environment variables:

• SKALD_API_KEY: Your Skald API key (required)

4. Restart Claude Desktop

Usage Examples

Chat with your knowledge base

Ask Cursor/Claude: "Check Skald for what are the instructions for running our Django server locally."

The assistant will query your Skald knowledge base and return an answer.

Search for memos

Ask Cursor/Claude: "Search Skald for the docs about our product vision"

The assistant will use the skald-search tool with semantic search to find relevant memos and display:

• Title
• UUID
• Summary
• Content snippet
• Relevance score (for semantic search)

If you had asked for "memos with Product Vision in the title", the agent would pick another search method such as title_contains.

Create a new memo

Ask Cursor/Claude: "Generate an API reference for my endpoints and upload it to Skald"

The assistant will create a new memo in your Skald knowledge base, which will be automatically processed and made searchable.

Tool Parameters

skald-chat

Parameter	Type	Required	Description
query	string	Yes	The question to ask your knowledge base
project_id	string	No	Project UUID (required when using Token Authentication)
filters	Filter[]	No	Optional filters to narrow the search context

skald-search

Parameter	Type	Required	Description
query	string	Yes	The search query
search_method	enum	Yes	One of: chunk_vector_search, title_contains, title_startswith
limit	number	No	Maximum results to return (1-50, default 10)
filters	Filter[]	No	Optional filters to narrow results

skald-create-memo

Parameter	Type	Required	Description
title	string	Yes	The title of the memo (max 255 characters)
content	string	Yes	The full content of the memo
project_id	string	No	Project UUID (required when using Token Authentication)
metadata	object	No	Custom JSON metadata
reference_id	string	No	External reference ID to match with your documents
tags	string[]	No	Tags for categorization
source	string	No	Source of the content (useful for integrations)

skald-get-memo

Parameter	Type	Required	Description
memo_id	string	Yes	The memo UUID or client reference ID
id_type	enum	No	Type of identifier: memo_uuid (default) or reference_id

skald-update-memo

Parameter	Type	Required	Description
memo_id	string	Yes	The memo UUID or client reference ID
id_type	enum	No	Type of identifier: memo_uuid (default) or reference_id
title	string	No	New title for the memo
content	string	No	New content for the memo
metadata	object	No	New metadata
client_reference_id	string	No	New client reference ID
source	string	No	New source
expiration_date	string	No	New expiration date

skald-delete-memo

Parameter	Type	Required	Description
memo_id	string	Yes	The memo UUID or client reference ID
id_type	enum	No	Type of identifier: memo_uuid (default) or reference_id

skald-generate

Parameter	Type	Required	Description
prompt	string	Yes	The prompt for document generation
rules	string	No	Optional style/format rules
filters	Filter[]	No	Optional filters to control which memos are used as context

Filter Object

Filters are used in skald-chat, skald-search, and skald-generate to narrow results:

Field	Type	Required	Description
field	string	Yes	The field to filter on
operator	enum	Yes	One of: eq, neq, contains, startswith, endswith, in, not_in
value	string or string[]	Yes	The value to filter by
filter_type	enum	Yes	native_field (e.g., source, tags) or custom_metadata

Example filter:

{
  "field": "source",
  "operator": "eq",
  "value": "notion",
  "filter_type": "native_field"
}

Development

Build

npm run build

Lint

npm run lint

Fix linting issues

npm run lint:fix

Troubleshooting

API Key Issues

If you get an error about a missing API key:

• For Cursor: Ensure the --key argument is set in your config
• For Claude Desktop: Ensure SKALD_API_KEY is set in the env section

Module Not Found

If you see "Cannot find module '@skald-labs/skald-node'":

npm install
npm run build

Connection Issues

Check the debug logs:

• Cursor: Check the MCP server logs in Cursor settings
• Claude Desktop: Check the logs in Claude Desktop developer settings