REST and MCP API

Prerequisites

• An email address for the knowmind account
• An access key of the form kmt_… with read, plus write for saving
• An HTTP client with TLS in your language

Steps

1. 1

   Create your knowmind account

   Enter your email address at knowmind.de. You receive a sign-in link by mail and use it to sign in. There is no password.

   Then create your workspace: name, short name and plan. The Private plan costs 0 € and is enough for this guide; the pricing page lists the others.

   Outcome: The welcome screen is open, offering “start by writing” and “connect my AI tool”. Three starter cards are already in your workspace.

2. 2

   Create an access key

   Create a key in the Cockpit under keys: read is enough for searching, write is needed for saving and linking. The key is shown only once.

   Note

   One key per application

   Create a separate key for every application. Then one can be revoked without stopping the others. In code it belongs in an environment variable, not in the source.

   Outcome: You have a key of the form kmt_….

3. 3

   Endpoint and authentication

   All requests go to https://knowmind.de, authenticated with the header Authorization: Bearer kmt_…. MCP has a single address, REST one per task; the German REST reference lists them all.

   textcopy

   MCP:     https://knowmind.de/api/mcp/v1
   REST:    https://knowmind.de/api/memory/recall
            https://knowmind.de/api/documents
            https://knowmind.de/api/karten
            https://knowmind.de/api/stats
   Header:  Authorization: Bearer kmt_…

   The MCP address answers either as a single JSON response or as an event stream, depending on what your client asks for in the Accept header. With no particular request you get plain JSON; with Accept: text/event-stream you get the stream some connectors expect.

   Outcome: A call with your key returns the tool list; without a valid key knowmind answers with HTTP 401.

   bashcopy

   curl -s -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. 4

   First call: tools, save, search

   The tool list shows what is available. Then save something and search for it — in a fresh workspace the three starter cards come back instead, marked as a starting point rather than a solid hit.

   bashcopy

   # List the tools
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   
   # Save
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {
         "name": "knowmind_store_memory",
         "arguments": {
           "memory_type": "semantic",
           "title": "Invoice routing",
           "content": "Invoices go to head office, never to a branch.",
           "source": "handbook"
         }
       }
     }'
   
   # Search
   curl -X POST https://knowmind.de/api/mcp/v1 \
     -H "Authorization: Bearer kmt_…" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {
         "name": "knowmind_recall_memories",
         "arguments": { "query": "Where do invoices go?", "k": 5 }
       }
     }'

   Outcome: Every answer is a JSON-RPC object with result or error. What you saved is found in the next call straight away.

5. 5

   The same from code

   TypeScript (Node 20 or newer):

   tscopy

   const TOKEN = process.env.KNOWMIND_TOKEN!;
   const MCP = "https://knowmind.de/api/mcp/v1";
   
   async function tool(name: string, args: Record<string, unknown>) {
     const response = await fetch(MCP, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${TOKEN}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: 1,
         method: "tools/call",
         params: { name, arguments: args },
       }),
     });
     if (!response.ok) throw new Error(`knowmind: HTTP ${response.status}`);
     return response.json();
   }
   
   const hits = await tool("knowmind_recall_memories", {
     query: "Who wrote the Müller contract?",
     k: 5,
   });
   console.log(hits);

   Python:

   pythoncopy

   import os, requests
   
   TOKEN = os.environ["KNOWMIND_TOKEN"]
   MCP = "https://knowmind.de/api/mcp/v1"
   HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
   
   def tool(name: str, args: dict) -> dict:
       response = requests.post(
           MCP,
           headers=HEADERS,
           json={
               "jsonrpc": "2.0",
               "id": 1,
               "method": "tools/call",
               "params": {"name": name, "arguments": args},
           },
           timeout=10,
       )
       response.raise_for_status()
       return response.json()
   
   print(tool("knowmind_recall_memories", {"query": "GDPR training?", "k": 5}))

   Outcome: The same hits as over curl, with the key from the environment.

6. 6

   Plan for the rate limit

   The rate limit applies to the tools that query the memory; saving, linking and reporting on the store do not count towards it. The two routes report it differently:

   • REST answers with HTTP 429 and names the waiting time in seconds in the Retry-After header.
   • MCP answers with HTTP 200 and an error field carrying the code -32004 and a sentence the AI tool can pass on. Retry logic keyed to the status code does not catch it; check the error field.

   Wait the time given, with a little jitter, and retry at most three times. The limits of your plan are on the German limits page.

How each tool authenticates

• Claude Desktop, Claude.ai, Claude Code and ChatGPT sign in with your knowmind account, authorised in the browser. You create no key for them.
• Cursor, Gemini CLI, the command line and n8n work with an access key. Setting them up from the welcome screen creates one for you.
• Your own applications send the key in the header on every call, as in the examples above.

Other tools that speak MCP

Any tool that can add an MCP server over HTTP with its own header can connect knowmind, even without a guide of its own — LM Studio or Continue, for instance. Many of them read a JSON file in this shape:

{
  "mcpServers": {
    "knowmind": {
      "url": "https://knowmind.de/api/mcp/v1",
      "headers": {
        "Authorization": "Bearer kmt_…"
      }
    }
  }
}

Where that file lives and what the fields are called is in the tool’s own documentation. knowmind receives the query and returns the hits; the rest of the conversation with the model never reaches knowmind. If a tool only supports locally started servers, the command line acts as a bridge with knowmind mcp.

Verify the result

Troubleshooting