sinups/layers-mcp-server repository overview

⁠Layers MCP Server

A Model Context Protocol⁠ server for Layers⁠. Connect AI assistants like Claude, Cursor, and Windsurf directly to your Layers workspace — manage projects, tasks, pages, and more through natural language.

Protocol: MCP Streamable HTTP (2025-06-18 spec) | Tools: 120 | Transport: HTTP

⁠Quick Start

⁠1. Get an API Token

1. Open your Layers workspace: Settings > Access Tokens
2. Click Add access token, give it a name, set an expiry
3. Set Access to read and write — a read-only token can list and search, but every create / update / assign / comment / delete is refused by the backend
4. Copy the token (starts with layers_ws_...) — it is shown only once

⁠2. Connect Your AI Assistant

Pick your client below. Replace YOUR_DOMAIN with your Layers instance URL and YOUR_TOKEN with the token from step 1.

⁠Claude Code (CLI)

claude mcp add-json layers '{
  "type": "http",
  "url": "https://YOUR_DOMAIN/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}'

Verify: claude mcp list — should show layers with 120 tools.

⁠Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "layers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://YOUR_DOMAIN/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

⁠Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "layers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://YOUR_DOMAIN/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

⁠Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "layers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://YOUR_DOMAIN/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

⁠VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "layers": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://YOUR_DOMAIN/mcp",
        "--header",
        "Authorization:Bearer YOUR_TOKEN"
      ]
    }
  }
}

⁠Claude.ai (Web)

Go to Claude.ai > Settings > Integrations > Add custom integration:

Enter your API token when prompted.

⁠Self-Hosted Deployment

Add the MCP server to your Layers Docker Compose stack.

⁠Where it sits in the Layers self-host stack

If you are standing up the full self-hosted Layers bundle — the Layers server, this MCP server, and the Layers AI Chat⁠ — this service is the middle layer. The request flow is:

browser → AI Chat → (internal network) MCP server :8091 → Layers REST API → Postgres

The chat (and any other in-cluster consumer) talks to the MCP server over the internal Docker network, sending each user's workspace token as a bearer:

LAYERS_MCP_URL = http://layers-mcp:8091/mcp

Issuing the workspace token the chat uses. The chat sends a Layers workspace token as the bearer. Create it once in your Layers instance under Settings > Access Tokens (it starts with layers_ws_… and is shown only once), then hand it to the chat as described in its hosting guide⁠.

In the self-host bundle the image is pulled as hissih/layers-mcp-server⁠; the env vars below (LAYERS_BACKEND_BASEURL, LAYERS_BACKEND_FORWARDINCOMINGAUTH, …) are the same regardless of which tag you pull. Point LAYERS_BACKEND_BASEURL at the Layers API over the internal network (e.g. http://layers-server:8080). The full end-to-end stack assembly (domains, SSO cookie, reverse proxy, voice) is documented in the chat repo — see its README⁠ and docs/hosting-guide.md⁠.

⁠Docker Compose

Add this service alongside your existing layers-server and layers-db:

layers-mcp:
  image: sinups/layers-mcp-server:latest
  restart: always
  depends_on:
    - layers-server
  environment:
    LAYERS_BACKEND_BASEURL: http://layers-server:8080
    LAYERS_BACKEND_FORWARDINCOMINGAUTH: "true"
    LAYERS_BACKEND_REQUIREINCOMINGAUTH: "true"
    LAYERS_BACKEND_BEARERTOKEN: ""
    # Address of the web app as a person opens it — links in tool output come from here
    LAYERS_BACKEND_FRONTENDBASEURL: https://app.example.com
    LAYERS_MCP_ENDPOINT: /mcp
    SERVER_PORT: "8091"
    SPRING_PROFILES_ACTIVE: server
  ports:
    - "8091:8091"
  networks:
    - layers-internal

Users connect to https://YOUR_DOMAIN/mcp using their personal API tokens from Settings > Access Tokens.

⁠Reverse Proxy

If your Layers instance uses a reverse proxy (nginx, Traefik, Caddy), route /mcp to the MCP container on port 8091. Example for Traefik labels:

labels:
  - traefik.enable=true
  - "traefik.http.routers.layers-mcp.rule=Host(`YOUR_DOMAIN`) && PathPrefix(`/mcp`)"
  - traefik.http.routers.layers-mcp.priority=200
  - traefik.http.services.layers-mcp.loadbalancer.server.port=8091

With nginx:

location /mcp {
    proxy_pass http://layers-mcp:8091;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 300s;
    proxy_buffering off;
}

⁠Standalone Docker

If you want to run the MCP server separately (not in the Layers Docker network):

docker run -d \
  --name layers-mcp \
  -p 8091:8091 \
  -e LAYERS_BACKEND_BASEURL=https://YOUR_DOMAIN \
  -e LAYERS_BACKEND_FORWARDINCOMINGAUTH=true \
  -e LAYERS_BACKEND_REQUIREINCOMINGAUTH=true \
  sinups/layers-mcp-server:latest

⁠Single-User Mode

For personal use or testing, you can set a static token so clients don't need to provide their own:

docker run -d \
  --name layers-mcp \
  -p 8091:8091 \
  -e LAYERS_BACKEND_BASEURL=https://YOUR_DOMAIN \
  -e LAYERS_BACKEND_FORWARDINCOMINGAUTH=false \
  -e LAYERS_BACKEND_REQUIREINCOMINGAUTH=false \
  -e LAYERS_BACKEND_BEARERTOKEN="Bearer layers_ws_YOUR_TOKEN" \
  sinups/layers-mcp-server:latest

Then connect clients to http://localhost:8091/mcp with no Authorization header needed.

⁠Configuration Reference

⁠Available Tools

120 tools grouped by what they work on. Every tool carries MCP annotations⁠ (readOnlyHint, destructiveHint, idempotentHint), so a client can ask before anything destructive happens.

This list is generated from the server's own catalogue — see scripts/render-readme-tools.mjs.

⁠Smart Features

Workspace Context — Call layers_workspace_context first to get a quick overview of projects, members, and recent pages. The AI assistant will know exactly where to create content.

Name Resolution — Use human-readable names instead of UUIDs:

"Create a task in project Design v2 and assign to Alice"

The server resolves projectName, assigneeName, statusName, and priorityName automatically.

Disambiguation — When a name matches multiple items, the server returns a helpful list:

Multiple projects match 'MCP'. Please be more specific:
  - MCP Testing  (id=b0f02a3d...)
  - MCP Integration Test  (id=dc399ea8...)
Use the exact name or provide the ID directly.

Auto-defaults — Missing fields get smart defaults:

• Status → first status in project (usually "Backlog")
• Priority → default priority (usually "Normal")
• Sprint → latest sprint, or auto-creates "Task List"
• Task type → "Task"

⁠Usage Examples

Browse your workspace

Find overdue work

Create a task

Read a document

Check project health

Plan a sprint

Manage team

⁠Troubleshooting

⁠Server not appearing in client

1. Verify JSON syntax: cat your-config.json | python3 -m json.tool
2. Check Node.js: node --version (need 18+)
3. Fully restart the client — Cmd+Q (macOS) / Alt+F4 (Windows), not just close the window
4. nvm users: Use the full path to npx (see Claude Desktop section above)

⁠401 Unauthorized on tool calls

Symptom: Server connects, lists 120 tools, but tool calls return 401.

Cause: Your token is from a different Layers instance than the MCP server URL.

Fix: Make sure the MCP server URL and the token are from the same Layers instance. A token created on workspace-a.layers.md will not work with an MCP server pointing to workspace-b.layers.md.

⁠Token expired or invalid

Symptom: 401 Unauthorized on all requests.

Fix: Create a new token in Settings > Access Tokens. Tokens start with layers_ws_ and are shown only once.

⁠Everything reads fine, but nothing can be changed

Symptom: 403 with TOKEN_SCOPE_READ_ONLY on any create / update / assign / comment / delete, while listing and search keep working.

Fix: The token was issued for reading only. Access level is chosen once, at creation, and cannot be changed afterwards — issue a new token in Settings > Access Tokens with Access: read and write and swap it into your client config. Retrying, or reaching for a different tool, will not help.

⁠OAuth popup appears (mcp-remote)

Symptom: Browser opens asking for OAuth login instead of using the token.

Fix: Clear the mcp-remote auth cache and restart:

rm -rf ~/.mcp-auth

⁠Timeout on startup

Fix: Set a longer timeout with the MCP_TIMEOUT environment variable:

{
  "mcpServers": {
    "layers": {
      "command": "npx",
      "args": ["mcp-remote", "https://YOUR_DOMAIN/mcp", "--header", "Authorization:Bearer YOUR_TOKEN"],
      "env": {
        "MCP_TIMEOUT": "10000"
      }
    }
  }
}

⁠Behind a corporate VPN

Add your CA certificate:

"env": {
  "NODE_EXTRA_CA_CERTS": "/path/to/corporate-ca.crt"
}

⁠Enable debug logging (mcp-remote)

npx mcp-remote https://YOUR_DOMAIN/mcp --debug

Logs are written to ~/.mcp-auth/.

⁠How It Works

AI Assistant (Claude / Cursor / Windsurf / VS Code)
        |
        |  MCP Streamable HTTP (2025-06-18)
        |  Authorization: Bearer layers_ws_...
        v
+------------------------------+
|      Layers MCP Server       |  :8091/mcp
|  Java 17 + Spring Boot 4     |
|  120 tools, 10 resources     |
|  8 prompts, 8 completions    |
+-------------+----------------+
              |  REST API + Bearer token (forwarded)
              v
+------------------------------+
|        Layers API            |  your-domain.com
+------------------------------+

Multi-user mode (default): Client token -> MCP Server -> Layers API (forwarded as-is)

Single-user mode: MCP Server static token -> Layers API (client sends no token)

⁠Build from Source

./mvnw -DskipTests package
java -jar target/layers-mcp-server.jar \
  --spring.config.location=file:./application-external.properties \
  --spring.profiles.active=server

See deploy/application-external.properties.example for configuration template.

⁠Docker Hub

docker pull sinups/layers-mcp-server:latest

Available for linux/amd64 and linux/arm64.

⁠Links

• Layers Platform⁠
• Docker Hub⁠
• Model Context Protocol⁠