PlusGPT MCP server

An MCP server that lets an agent read, write, search and question a PlusGPT knowledge base instance. Built with FastMCP and served over streamable HTTP.

The server stores no credentials. Each caller authenticates with their own Knowledge Base API key, and every request is made as that user, so an agent can reach exactly what its key can reach and nothing else.

Tools

Orientation

Reading

Writing

Sharing

Everything here hands something to somebody else, so each tool says plainly how far the grant reaches.

Files

Indexing

Every tool carries a description written for an agent to read, including what to pass, what comes back, and which tool to reach for next.

What a key can reach

There is no authority here beyond the caller's own key: every request is made with it, and the Knowledge Base's own permission rules decide the answer. Two limits are this server's own, because they are not the API's to enforce:

• Ids are checked before they become part of a request path, so a tool cannot be steered onto an endpoint other than the one it describes.

• upload_document's url is fetched only from public addresses, and only up to 50 MB. The server sits on the same private network as the database, the object store and the vector store; a caller-chosen URL must not reach them.

Pages have a type

Every page can be filed as a type - Letter, Invoice, Runbook, whatever this knowledge base actually uses. It is free text, not a fixed set, so list_page_types exists to show the vocabulary already in use: reusing "Invoice" beats inventing "Invoices" and splitting the category in two. create_page, update_page and upload_document all accept one.

Several files at once

upload_document takes either one file (content_base64) or many (files_base64 with matching filenames). By default each file becomes its own page named after its own content. With combine=true they become a single page in the order given, which is what a document that arrived as a set of scans needs. One doc_type applies to the whole upload.

Related MCP server: mcp-rag

Connecting a client

The endpoint is https://plusgpt.io/mcp and the transport is streamable HTTP. Authenticate with a Knowledge Base API key, created in the app under Settings → API keys, sent as a bearer token:

{
  "mcpServers": {
    "plusgpt": {
      "type": "http",
      "url": "https://plusgpt.io/mcp",
      "headers": { "Authorization": "Bearer kb_your_key_here" }
    }
  }
}

Give the key the write scope if the agent should create or edit pages. A read-only key still searches and asks; writes are refused with a message saying so.

The skill

Connecting the server tells an agent what it can call. It does not tell it how to behave - and the two mistakes that matter most are behavioural: reading a PDF itself instead of passing the bytes, and filing a document wherever without asking. skills/plusgpt/ is a skill that settles both.

skills/plusgpt/
  SKILL.md              what PlusGPT is, when to use it, the whole tool list
  references/files.md   handing over files: formats, limits, combine, failures
  references/writing.md writing pages by hand: markdown support, page quality

Copy the directory into wherever the agent loads skills from - for Claude Code that is .claude/skills/plusgpt/ in a project or ~/.claude/skills/plusgpt/ for every project:

cp -R skills/plusgpt ~/.claude/skills/

It is plain markdown with YAML frontmatter, so any agent that reads skills can use it as-is. Its central instruction is that the agent passes files straight to upload_document rather than transcribing them, because a vision model on the server side reads scans, photographs and handwriting better than a transcription does - and keeps the original attached to the page.

tests/test_skill.py checks the skill against the running server: every tool is mentioned, no invented tool is named, every promised upload_document parameter exists, and the accepted formats match the ones the server really takes. If a tool is renamed and the skill is not updated, that test fails.

Running it

With Docker, pointed at a Knowledge Base you can reach:

docker run --rm -p 8000:8000 \
  -e KB_API_URL=https://plusgpt.io/api/v1 \
  shanaka95/knowledgebase-mcp:latest

Alongside the Knowledge Base stack, as a service in the same compose file:

mcp:
  image: shanaka95/knowledgebase-mcp:latest
  environment:
    KB_API_URL: http://backend:8000/api/v1
  restart: unless-stopped

For development:

uv sync
uv run python -m kb_mcp          # serves http://127.0.0.1:8000/mcp
uv run pytest tests -q
uv run ruff check src tests && uv run mypy

Configuration

Every setting is an environment variable; see .env.example. The one that matters is KB_API_URL, which is a container name inside a deployment and a public URL from anywhere else.

How authentication works

1. The client sends Authorization: Bearer kb_....

2. The server calls GET /users/me on the Knowledge Base with that key.

3. A rejected key, or an unreachable Knowledge Base, denies the request.

4. A verified key is cached briefly so a burst of tool calls is one auth check.

5. The same key is then used for every API call the tools make.

Revoking a key in the app stops it working here within AUTH_CACHE_SECONDS.