Early PreviewJoin us on the road to v1.0 — help shape the future of specification engineering.Get Involved →
SPECLAN mascotSPECLAN

MCP Server

Ask your AI assistant "what does F-1234 actually require?" and it usually guesses, or greps, or reads whatever file happens to be open.

SPECLAN ships a server that removes the guessing. Start it from a panel in VS Code, point your assistant at it, and the assistant gets thirteen purpose-built tools for your specification tree: ranked search, entity lookup with ancestors and children, graph traversal, SQL queries, project statistics — and, if you allow it, the ability to create and update specs directly.

This is the headline capability of this release. This page covers starting the server, configuring it safely, and connecting your particular assistant.

What MCP Is, Briefly

Model Context Protocol is an open standard for connecting AI assistants to data sources. An assistant that speaks MCP can use tools that any MCP server offers, without either side knowing about the other in advance.

SPECLAN is such a server. You do not need to understand the protocol — you need to start the server and paste one line of configuration into your assistant.

Opening the Control Panel

Everything happens in one place. Open the Command Palette (Cmd/Ctrl+Shift+P) and run:

SPECLAN: Open MCP Server Control Panel

The panel has a status line and four sections: Configuration, Authentication, Tools, and Connect a client.

Server status

The status line shows one of three states:

State Meaning
Stopped Not running. Clients cannot connect.
Starting… Coming up. Usually momentary.
Running Accepting connections. The panel shows the URL and how many tools are live.

The Start Server button becomes Stop Server while running.

The server runs only while VS Code is open. Close the window and it stops; clients lose their connection until you start it again. To have it come up on its own, enable speclan.mcpServer.autoStart in Settings — the server then starts whenever you open a SPECLAN project.

The server listens on 127.0.0.1 — your own machine only. It is not reachable from your network, and there is nothing to expose to the internet.

Configuration

Port

Default 3000, giving the endpoint:

http://127.0.0.1:3000/mcp

If something else already uses that port, starting fails with "Port 3000 is already in use". Change the port in the panel and start again. If you change it after a client is configured, update the client too — the URL is part of its configuration.

Authentication

The Authentication section controls whether clients must prove themselves.

When no key is set, the panel shows Off — open localhost: any program running on your machine can connect and use the enabled tools. For a personal machine that is usually fine, and it is the zero-friction default. It is worth knowing rather than discovering.

Click Generate API Key to change that. SPECLAN generates a random key, and the panel switches to showing the last four characters and the header clients must send:

X-API-Key: ••••••••abcd

Once a key exists, every request must carry that header. The button becomes Regenerate Key (mint a new one, invalidating the old) and Clear Key removes it, returning to open localhost.

The key is stored in VS Code's encrypted secret storage. It is not synchronised to your other machines — generate a separate key on each, or set speclan.mcpServer.apiKey in Settings if you want to control the value yourself.

When you regenerate or clear the key, every configured client must be updated. The snippets in Connect a client always contain the current key, so re-copying is the fastest fix.

Tools

The Tools section lists all thirteen tools in three groups. The header summarises the current selection, e.g. "13 of 13 enabled".

Group Tools What the assistant can do
Read specs speclan_search, speclan_get, speclan_list, speclan_traverse, speclan_sql, speclan_project Ranked search, read an entity with its ancestors and children, list with filters, walk the spec graph, run read-only SQL over the tree, get project info and statistics
Write specs speclan_create, speclan_update, speclan_transition, speclan_link, speclan_move, speclan_delete Create entities, edit them, move them through the status lifecycle, link them, relocate them, delete them
Artifacts speclan_artifact List, read, add and remove artifacts

All thirteen are enabled by default. Untick any you would rather not expose; each group has All and None toggles.

Tool selection is locked while the server runs — the panel shows "Stop the server to change tools." Stop it, adjust, start again.

Read-only mode

For a stronger guarantee than unticking boxes, turn on speclan.mcpServer.readOnly in Settings. The six write tools are then not registered at all — an assistant cannot call them because it never learns they exist — and speclan_artifact is narrowed to listing and reading.

This is the setting to use when you want an assistant that can answer questions about your specs but must never change them. The panel shows "Read-only mode is on" while it applies.

Read-only and per-tool selection combine: read-only removes the write surface, and your selection narrows what remains.

Connect a Client

Start the server first — the snippets contain the live URL and key.

GitHub Copilot (VS Code)

Nothing to configure. SPECLAN advertises the running server to VS Code directly; Copilot Chat picks it up on its own. Look for SPECLAN in Copilot's tools list, then ask it something about your specs.

This requires VS Code 1.101 or newer. On older versions the feature is simply absent — use the Cursor JSON approach below, which VS Code also accepts.

Claude Code

Click Claude Code CLI in Connect a client to copy the command, then run it in your project:

claude mcp add --transport http speclan http://127.0.0.1:3000/mcp --header "X-API-Key: your-key-here"

The --header argument is included only when a key is set. Verify with /mcp inside Claude Code — speclan should be listed with its tools.

Cursor

Click Cursor mcp.json to copy this fragment, and merge it into Cursor's MCP configuration:

{
  "mcpServers": {
    "speclan": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "X-API-Key": "your-key-here"
      }
    }
  }
}

The headers object is omitted when no key is set. Cursor shows the server in its MCP settings once saved.

Claude Desktop

Claude Desktop uses the same mcpServers shape as Cursor. Copy the Cursor mcp.json snippet and merge it into claude_desktop_config.json, then restart Claude Desktop. The SPECLAN tools appear in the attach menu.

Any other MCP client

Plenty of assistants speak MCP, and their configuration formats differ. SPECLAN's side is only ever these two values:

  • Endpoint — http://127.0.0.1:3000/mcp (streamable HTTP transport)
  • Header — X-API-Key: <your key>, only if you generated one

Give those to your client in whatever form it expects; consult its documentation for where its MCP configuration lives. Most clients that accept a URL use the same mcpServers shape shown above, so the Cursor snippet is usually a good starting point.

Clients that cannot use HTTP

Some assistants only launch MCP servers as a subprocess over stdio. SPECLAN bundles a stdio server for exactly that case. Point the client at:

node <extension-path>/mcp-stdio/speclan-stdio.js --specRoot=/path/to/your/project/speclan

Useful flags: --readOnly for a read-only surface, and --owner=you@example.com to set the owner recorded on entities the assistant creates. SPECLAN_ROOT and SPECLAN_OWNER work as environment variables instead.

This server runs independently of the control panel — the panel's start/stop and settings do not apply to it. Note that <extension-path> contains the extension version and therefore changes when SPECLAN updates, so this configuration needs revisiting after an upgrade. Prefer the HTTP transport when your client supports it.

Checking It Works

Ask your assistant something only your specifications can answer:

  • "Search my specs for anything about authentication."
  • "Show me F-1234 with its parent chain and child requirements."
  • "How many requirements are still in draft?"
  • "Which features contribute to G-002?"

The assistant reads the live tree. Edit a spec in VS Code and the next question sees the change — nothing to restart, no re-index.

Troubleshooting

You just updated SPECLAN and the panel or server looks wrong. A VS Code window keeps running the version it started with until you reload it, so a window opened before the update is still running the previous extension — with the previous MCP server, or none at all. Run Developer: Reload Window (Cmd/Ctrl+Shift+P) in that window. Worth doing first whenever something behaves as though a feature you just installed isn't there.

The client cannot connect. Check the panel says Running — the server stops when VS Code closes. Then check the port in the client's configuration matches the panel. If a key is set, the client must send it; re-copy the snippet, since it always carries the current key.

"Port 3000 is already in use." Another program has the port. Pick a different one in the panel, start again, and update your clients with the new URL.

The client connects but shows no tools. Everything is unticked in the Tools section, or read-only mode is on and only write tools were selected. Check the header summary — it shows how many tools are enabled.

The assistant says it cannot create or update specs. Either read-only mode is on, or the write tools are unticked. Both are deliberate; turn off speclan.mcpServer.readOnly and re-tick the Write specs group, then restart the server.

Anything else. Open the Output panel (Cmd/Ctrl+Shift+U) and choose SPECLAN Debug. The server logs every start, stop, and tool call there, including the port, tool count, and whether authentication is on.

Related

  • Local LLM — run the assistant itself on your own machine too
  • Getting Started — new to SPECLAN and want the basics first