MCP Base¶

The MCP base exposes G6Solver via the Model Context Protocol, enabling AI assistants like Claude Code and Cursor to invoke G6 tools natively. It is built on FastMCP and supports stdio (local, default) and SSE (network) transports.

Transport modes¶

The transport is selected via the MCP_TRANSPORT environment variable.

stdio (local, default)SSE (network)

Default mode. G6 runs locally as a subprocess of the MCP client, communicating over stdin/stdout. All components execute locally — no network required.

claude mcp add g6 --transport sse \n  --url https://g6solver.com/mcp/sse \n  --header "Authorization: Bearer YOUR_API_KEY"

Your desktop license handles authentication. No network middleware or rate limiting is applied — this is the expected default experience for all users.

Server-Sent Events over HTTP. For self-hosted multi-user deployments with full middleware (auth, rate limiting, tier gating).

claude mcp add g6 --transport sse \
  --url https://your-server.example.com/mcp/ \
  --header "Authorization: Bearer YOUR_API_KEY"

SSE mode binds to MCP_HOST (default 0.0.0.0) on MCP_PORT (default 8080).

Middleware stack¶

When running in SSE mode with POSTGRES_PASSWORD set, the server installs a middleware stack on every registered tool:

authenticate     -> validate Bearer token, extract user context (tier, customer_id)
check_rate_limit -> Redis sliding-window counter (60s window, Lua script)
is_tool_allowed  -> tier-based tool gating (TIER_TOOLS mapping)
check_credits    -> PAYG credit verification (if tier == "payg")
[execute tool]
deduct_credits   -> PAYG credit deduction on success

PAYG credits

The credit check/deduction middleware is present in the codebase but PAYG billing is not currently enabled (ENABLE_CREDITS=false). These middleware steps are only active when credits are explicitly enabled.

The middleware is installed by monkey-patching each tool's fn attribute in the FastMCP tool manager. This ensures all access paths are protected regardless of how FastMCP routes requests.

Stdio mode: no network middleware

When MCP_TRANSPORT=stdio (the default) or POSTGRES_PASSWORD is not set, tools run without any network middleware. This is the expected default experience for all users. Your desktop license handles authentication locally.

Launch readiness risks¶

For the first-user launch path, MCP should be treated as ready only after these checks have passed:

Risk	What to verify
Helper layer vs full install	`mvp.base_helpers` returns structured `ok` envelopes and normalizes typed component outputs in component-level tests. Treat that as necessary but not sufficient: the full launch path still needs registry discovery, dependencies, MCP startup, and one complete workflow verified together.
Clean-machine install	On a machine without prior G6 state, run `claude mcp add g6 --transport sse \n --url https://g6solver.com/mcp/sse \n --header "Authorization: Bearer YOUR_API_KEY"`, call the status tool, and complete one starter workflow.
Claude Code local setup	Confirm `claude` is available on `PATH` and authenticated before relying on `agent_claude` component MCP tools. A missing CLI should show as degraded status, not as a silent failure.
Local paid-API spend	Stdio mode has no central billing middleware. Components that call paid LLM APIs require explicit consent, but production spend caps must be enforced by provider quotas, remote middleware, or account-level limits.

MCP tools by category¶

The MCP server advertises 262 tools, gated by license tier. The categories below cover the principal tool families.

Per-category counts

The per-category counts below were re-derived by counting the @server.tool() registrations in each bases/mvp/mcp/tools/*.py module. Two rows were stale: T1 Core was missing describe_component and job_input_schema (9 -> 11), and T5 Orchestration was missing reliability_solve (4 -> 5); the erroneous sagemath_* reference (a formal_methods tool, not a Core tool) has been removed. These fifteen categorized rows sum to 111 tools -- a subset of the 262 tools the server advertises; most of the remainder are reached through the invoke_component dispatcher rather than belonging to one of these named tiers.

Tier	Tools	Plans
T1 Core (11)	`decompose_goal`, `run_bayesian`, `run_automl`, `recommend_algo`, `system_status`, `list_components`, `describe_component`, `invoke_component`, `invoke_component_typed`, `run_pipeline`, `job_input_schema`	All
T2 Navigator (6)	`nav_discover`, `nav_search`, `nav_recommend`, `nav_inspect`, `nav_stats`, `nav_health`	Researcher+
T3 Guide (5)	`guide_ask`, `guide_how_to`, `guide_find_tool`, `guide_plan_workflow`, `guide_system_overview`	All
T4 Pipelines (5)	`run_research_pipeline`, `run_codegen_pipeline`, `run_data_pipeline`, `run_safety_pipeline`, `run_knowledge_pipeline`	Builder
T5 Orchestration (5)	`compose_and_run`, `cross_call_tool`, `dependency_graph`, `explain_component`, `reliability_solve`	Builder
T6 EvoSkill (7)	`evolve_skills`, `propose_skill`, `generate_skill`, `evaluate_program`, `list_programs`, `get_frontier`, `feedback_descent_run`	Builder
T7 Self-Optimisation (4)	`optimize_pipeline`, `optimization_report`, `optimization_stats`, `optimization_apply`	Builder
T8 Bias Evolution (7)	`bias_snapshot`, `bias_observe`, `bias_evaluate`, `bias_evolve`, `bias_apply`, `bias_rollback`, `bias_ground_check`	Builder
T9 Self-Training (7)	`self_training_audit`, `self_training_audit_all`, `self_training_scorecard`, `self_training_promote`, `self_training_flag`, `self_training_rubric`, `self_training_rubrics`	Builder
T10 Tier Manager (5)	`tier_get_status`, `tier_propose_advance`, `tier_confirm_advance`, `tier_reject_advance`, `tier_cap`	Researcher+ (status), Builder (mutate)
T11 Patch Service (5)	`patch_report_bug`, `patch_check_status`, `patch_apply`, `patch_list`, `patch_rollback`	Researcher+ (report/status), Builder (apply/rollback)
T12 Clean Room (3)	`get_component_spec`, `configure_component_bypass`, `list_bypasses`	Builder
T13 Learning Layer (8)	`learning_build_dataset`, `learning_train`, `learning_evaluate`, `learning_get_theories`, `learning_get_artifacts`, `learning_get_status`, `learning_export_harness`, `learning_import_harness`	Builder
T14 MCP Lifecycle (5)	`nav_mcp_load`, `nav_mcp_unload`, `nav_mcp_list_active`, `nav_mcp_evict_idle`, `nav_mcp_registry`	Builder
T15 Task Tracker (28)	`task_create`, `task_list`, `task_get`, `task_claim`, `task_complete`, `task_update_progress`, `task_approve`, `task_reject`, + 20 more	All

Task tracker storage scope

The Task Tracker MCP tools use the task_tracker component's local SQLite store by default. This is suitable for single-user MCP installs, demos, and pilot workflows. It is not a shared multi-user task backend unless deployed behind a single writer or migrated to a server database with tenant isolation, migrations, backups, and monitoring.

Free Trial accounts receive temporary Builder access at the Free Trial rate limit.

Component MCP sub-packages¶

Most components are not advertised as individual MCP tools. They are reached through the invoke_component dispatcher, which takes a component name, an operation, and a JSON parameter blob — the same path described on the MCP protocol page. Components organise their operations internally as MCP sub-packages; 212 of the 270 components own at least one, across 244 sub-packages.

Per-component operation counts previously published here (for example goal_engine and formal_methods) are withdrawn: the figures disagreed across three different pages and none could be reproduced against the registry. They will be republished only once derived from the code.

Configuration¶

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport: `stdio` or `sse`
`MCP_HOST`	`0.0.0.0`	SSE bind host
`MCP_PORT`	`8080`	SSE bind port
`POSTGRES_PASSWORD`	--	Enables auth middleware when set
`REDIS_URL`	`redis://redis:6379/0`	Redis for rate limiting
`MCP_RATE_LIMIT_FREE`	`10`	Free tier req/min
`MCP_RATE_LIMIT_BASIC`	`100`	Basic tier req/min
`MCP_RATE_LIMIT_PREMIUM`	`500`	Premium tier req/min
`MCP_RATE_LIMIT_PAYG`	`50`	PAYG tier req/min (inactive by default)

Deployment¶

# Local usage (stdio, default) — the shipped desktop binary
g6 --mcp

# Network deployment (SSE with middleware) — self-hosted server distribution
MCP_TRANSPORT=sse POSTGRES_PASSWORD=xxx python -m mvp.mcp

# Docker (network deployment)
docker build -f bases/mvp/mcp/Dockerfile -t g6-mcp .
docker run -p 8080:8080 -e MCP_TRANSPORT=sse g6-mcp

Source files¶

File	Purpose
`bases/mvp/mcp/__main__.py`	Entry point, transport selection
`bases/mvp/mcp/server.py`	Lazy FastMCP singleton, `_LazyMCP` proxy, backward-compat re-exports
`bases/mvp/mcp/tools/__init__.py`	`register_all_tools()` — imports and registers all 15 tier modules
`bases/mvp/mcp/tools/core.py`	T1 Core (10 tools)
`bases/mvp/mcp/tools/navigator.py`	T2 Navigator (6 tools)
`bases/mvp/mcp/tools/guide.py`	T3 Guide (5 tools)
`bases/mvp/mcp/tools/pipelines.py`	T4 Pipelines (5 tools)
`bases/mvp/mcp/tools/orchestration.py`	T5 Orchestration (4 tools)
`bases/mvp/mcp/tools/evoskill.py`	T6 EvoSkill (7 tools)
`bases/mvp/mcp/tools/optimization.py`	T7 Optimization (4 tools)
`bases/mvp/mcp/tools/bias_evolution.py`	T8 Bias Evolution (7 tools)
`bases/mvp/mcp/tools/self_training.py`	T9 Self-Training (7 tools)
`bases/mvp/mcp/tools/tier_manager.py`	T10 TierManager (5 tools)
`bases/mvp/mcp/tools/patch_service.py`	T11 Patch Service (5 tools)
`bases/mvp/mcp/tools/clean_room.py`	T12 Clean Room (3 tools)
`bases/mvp/mcp/tools/learning.py`	T13 Learning Layer (8 tools)
`bases/mvp/mcp/tools/mcp_lifecycle.py`	T14 MCP Lifecycle (5 tools)
`bases/mvp/mcp/tools/tasks.py`	T15 Task Tracker (28 tools)
`bases/mvp/mcp/tools/_deps.py`	Shared lazy-import helpers
`bases/mvp/mcp/middleware.py`	Re-exports `TIER_TOOLS` / `is_tool_allowed` from `mvp.middleware`
`bases/mvp/mcp/auth.py`	Bearer token authentication
`bases/mvp/mcp/rate_limiter.py`	Redis sliding-window rate limiter
`bases/mvp/mcp/usage.py`	PAYG credit check and deduction