Connect MCP servers to Sculptor — filesystem, GitHub, Context7, and more

MCP (Model Context Protocol) is how AI assistants call tools on other systems—read files, search docs, open tickets—through a standard wire format instead of custom plugins per app.

Sculptor can consume MCP servers so your Strategy Pack coach and Agentic runs use those tools in the same turn as your library assets.

What MCP is (in plain language)

Think of MCP as a USB port for AI tools:

• An MCP server advertises tools (search, read_file, resolve_library_id, …).
• An MCP client (here: Sculptor’s Next.js server during /api/chat/agent) lists those tools, lets the model pick one, runs it, and feeds results back into the conversation.

Without MCP, the model only sees text you typed. With MCP, it can act—under your configuration and credentials.

How Sculptor uses external MCP servers

When MCP is enabled for a surface:

1. Sculptor opens sessions to every configured server (stdio subprocesses and/or remote HTTP).
2. Tool names are merged into the model’s function list (with optional namespace prefixes).
3. The server runs a non-streaming tool loop against your LLM provider (OpenRouter, Ollama, org defaults, etc.).
4. The UI receives final assistant text as SSE—tool rounds happen server-side first.

You can attach many servers at once (for example filesystem + documentation + GitHub), as long as each is listed and names do not collide.

Two configuration layers

Layer	Who configures	Transport	Used when
Environment MCP	Operator on the Next.js host	SCULPT_MCP_STDIO_SERVERS, SCULPT_MCP_URL_SERVERS	Personal / BYOK chat without org MCP, or host-level defaults
Organisation MCP	Admin/Editor on Company account	HTTP/SSE URLs stored in Postgres	orgId sent on /api/chat/agent; no merge with env stdio for that request

Members control privacy toggles in Settings: enable org MCP for chat and/or Agentic separately.

Per-thread overrides exist for conversations and agent runs (disable specific org servers for one thread).

Connect well-known MCP servers (examples)

Replace paths, tokens, and URLs with your own. Stdio MCP runs on the Sculptor server host—treat commands as privileged.

1. Filesystem (read a project folder)

Official package: @modelcontextprotocol/server-filesystem.

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
  "toolNamespace": "fs"
}

Add the object inside SCULPT_MCP_STDIO_SERVERS='[ ... ]' in .env.local (development) or production env. Restart the Next.js / Docker web service after changes.

Security: only point at directories you are willing to expose to the model; restrict who can edit env on the host.

2. GitHub (issues, repos, code search)

Community servers vary by package; a common pattern is an MCP package that expects GITHUB_PERSONAL_ACCESS_TOKEN in the child process env:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." },
  "toolNamespace": "github"
}

Use a fine-scoped token; rotate if leaked. Prefer org MCP HTTP gateways if your enterprise already hosts GitHub MCP centrally.

3. Context7 (up-to-date library documentation)

Context7 is a popular HTTP documentation MCP. On Company account → MCP servers, add a server URL from Context7’s docs and set the API key (prefix ctx7sk) via API token preset or Headers JSON (Authorization: Bearer …).

Use Validate on the server row—Sculptor runs list-tools plus a harmless probe call so auth failures surface before a long Agentic run.

4. Hosted / Streamable HTTP MCP

For gateways that speak Streamable HTTP (preferred) or legacy SSE:

{
  "url": "https://your-mcp-host.example/mcp",
  "transport": "streamableHttp",
  "toolNamespace": "hosted",
  "headers": { "Authorization": "Bearer YOUR_TOKEN" }
}

Place objects in SCULPT_MCP_URL_SERVERS='[ ... ]'.

Default stdio: sculptor-data-server

If SCULPT_MCP_STDIO_SERVERS is unset, Sculptor still starts the built-in sculptor-data-server (comments/tasks tooling) with namespace sculptor. Add additional servers in the same JSON array when you need more than that.

Organisation MCP workflow (teams)

1. Admin/Editor → Company account → add HTTP MCP server (name, URL, transport, headers).
2. Validate connection; fix keys until ok: true.
3. Each member → Settings → enable Organisation MCP in chat and/or Agentic if they want tools attached.
4. Optional: per-conversation or per-agent-run override to disable a noisy server for one session.

Stable error codes (for support): ORG_MCP_NONE, MCP_CHAT_DISABLED, MCP_AGENTIC_DISABLED.

Model and provider requirements

• Use models that support tool / function calling (OpenRouter model choice matters).
• Ollama paths skip forced tool_choice: required for compatibility; tool support still depends on the model.
• Tool rounds are capped (see lib/mcp/constants.ts); large tool outputs are truncated before returning to the model.

What to prepare before enabling MCP

• Approved list of which external systems the coach may touch.
• Secrets in headers or env—not in chat messages.
• Egress policy for org HTTP MCP (URLs are fetched from the server).
• A fallback plan when MCP fails (disable MCP in Settings to return to streaming chat proxy).

Who should own MCP configuration

Role	Task
Platform / DevOps	Env arrays on production host, process allowlists for stdio
Org Admin	Company account servers, rotation of API keys
Member	Personal toggles for chat vs Agentic
Strategy lead	Decide which tools are allowed during pack runs

Examples from the real world (names changed)

Hardware startup. Filesystem MCP pointed at an /exports/specs folder let the coach pull CAD release notes into /tech without manual uploads—namespace fs avoided clashing with built-in sculptor tools.

Scale-up SaaS. Context7 MCP on the org account gave every product manager the same library-docs tool during /backlog chats; validate caught an expired API key before a board dry-run.

Use this in Sculptor tomorrow

1. For local/dev: add one stdio server to .env.local, restart next dev or Docker web.
2. For production org: Company account → MCP server → Validate → members enable MCP in Settings.
3. Send a chat message that requires external data (“summarize open GitHub issues for this repo”) with MCP enabled.
4. Read Sculptor as an MCP server if you also want Claude Desktop or Cursor to read your Sculptor library from outside the app.

Keywords: connect MCP to Sculptor, Model Context Protocol startup, Context7 MCP setup, GitHub MCP server, filesystem MCP JSON env.