Skip to content

Connect an MCP client

KGForEdGlobalMCP can be reached in two ways. Locally, an MCP host starts the server as a child process over STDIO. When the server is hosted, an MCP client connects to its Streamable HTTP endpoint by URL. In both cases the client communicates over the MCP protocol and uses the returned tools, resources, and prompts as context for client-side reasoning. The MCP surface is identical across the two transports.

Claude Desktop is the default local-development integration. Other MCP hosts that support custom STDIO servers can use the same server launch contract, but their configuration files and UI steps are client-specific.

If someone has given you a hosted URL, skip to Connect to a hosted server; no local installation is required.

Local connection model

%%{init: {"themeVariables": {"fontSize": "18px"}}}%%
flowchart LR
    A[MCP host] -->|starts child process| B[uv]
    B --> C[python -m kgfegmcp.mcpb_server]
    C --> D[FastMCP STDIO server]
    D --> E[Accepted catalog and services]
    E --> D
    D -->|tools, resources, prompts| A
Hold "Alt" / "Option" to enable pan & zoom

Before configuring a client

Verify the repository runtime first:

uv --directory backend run --locked --no-dev kgfegmcp-stdio-smoke

Do not use the desktop client as the first diagnostic surface. A passing smoke test separates server startup and package-loading problems from client configuration problems.

Claude Desktop on macOS

The confirmed manual configuration file is:

~/Library/Application Support/Claude/claude_desktop_config.json

1. Find the required absolute paths

From the repository root, run:

command -v uv
pwd

You need:

  • the absolute path to the uv executable; and
  • the absolute path to the repository root.

Desktop applications do not necessarily inherit the same shell PATH or working directory as your terminal, so use absolute paths in the configuration.

2. Add the MCP server configuration

Add the following member beneath the existing top-level mcpServers object. Replace the placeholder paths with the values from your machine and preserve unrelated Claude Desktop settings.

{
  "mcpServers": {
    "curriculum-knowledge-graph": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/repository/backend",
        "run",
        "--locked",
        "--no-dev",
        "python",
        "-m",
        "kgfegmcp.mcpb_server"
      ],
      "env": {
        "KGFEGMCP_CONFIG_ROOT": "/absolute/path/to/repository/config",
        "KGFEGMCP_DATA_ROOT": "/absolute/path/to/repository/data",
        "KGFEGMCP_ENV": "local",
        "KGFEGMCP_GRAPH_PACKAGES_ROOT": "/absolute/path/to/repository/data/graph_packages",
        "KGFEGMCP_INVALID_PACKAGE_POLICY": "fail",
        "KGFEGMCP_LOG_LEVEL": "INFO",
        "KGFEGMCP_PROFILE_ROOT": "/absolute/path/to/repository/config/profiles",
        "KGFEGMCP_PROMPT_ROOT": "/absolute/path/to/repository/config/prompts",
        "PATHS_PROJECT_DIR": "/absolute/path/to/repository"
      }
    }
  }
}

If the file already contains other mcpServers, add curriculum-knowledge-graph alongside them instead of replacing the entire object.

3. Validate the JSON

On macOS, validate the configuration before restarting Claude Desktop:

jq empty "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

No output means the JSON parsed successfully.

4. Fully restart Claude Desktop

Quit the application completely:

osascript -e 'quit app "Claude"'

Then reopen Claude Desktop. A window close may not be sufficient if the application process remains active.

5. Enable the connector

In a new conversation, enable curriculum-knowledge-graph under Connectors.

Use this as the first connection check:

Use the curriculum-knowledge-graph connector to list all available frameworks.

If framework snapshots are returned, the MCP host has successfully started the server and completed tool discovery.

Generic STDIO launch contract

For another MCP host, the important runtime contract is the same even if the client's configuration syntax differs.

Executable:

/absolute/path/to/uv

Arguments:

--directory
/absolute/path/to/repository/backend
run
--locked
--no-dev
python
-m
kgfegmcp.mcpb_server

The explicit repository environment variables shown in the Claude Desktop example are a safe way to make runtime input locations independent of the host's working directory.

Do not substitute a filesystem Python entry point

Use python -m kgfegmcp.mcpb_server intact Launching src/kgfegmcp/mcpb_server.py directly can cause Python package-name shadowing and break imports from the external MCP SDK.

Connect to a hosted server

A hosted deployment exposes the server at a Streamable HTTP endpoint:

https://<service-domain>/mcp

Nothing is installed or started on your machine. The endpoint is unauthenticated, so the URL is the only value a client needs.

Claude custom connector

In Claude, open the connector settings, add a custom connector, give it a name such as curriculum-knowledge-graph, and enter the endpoint URL, including /mcp. Leave the authentication fields empty. On Team and Enterprise plans an organization owner adds the connector first; members then enable it for themselves.

Enable the connector in a new conversation and use the same first connection check as the local path:

Use the curriculum-knowledge-graph connector to list all available frameworks.

Claude Code

claude mcp add --transport http curriculum-knowledge-graph https://<service-domain>/mcp

Other MCP clients

Any client that supports the Streamable HTTP transport can connect with the same URL.

Verify a hosted endpoint

From a repository checkout, run the HTTP smoke command against the endpoint:

uv --directory backend run --locked --no-dev kgfegmcp-http-smoke \
  --url https://<service-domain>/mcp

See Hosted deployment for how the hosted service is built and operated.

What the host is responsible for

The MCP host is the reasoning and generation layer. The server is responsible for:

  • accepted package loading and validation;
  • framework and capability discovery;
  • lexical and profile-governed code search;
  • exact standards retrieval and bounded hierarchy traversal;
  • rights-aware resources;
  • deterministic comparison and progression evidence; and
  • deterministic prompt rendering.

The host may synthesize, explain, compare, or draft from returned evidence, but those model-generated conclusions are not automatically source-asserted curriculum claims.

Optional MCPB connection path

The repository can also build a deterministic .mcpb bundle for distribution. Client installation behavior for custom extensions can vary by Claude Desktop build, so manual claude_desktop_config.json registration remains the confirmed local-development path.

See MCPB packaging for the packaging contract and staged-runtime smoke test.

Troubleshooting

The connector does not appear

Confirm all of the following:

  • command is the absolute result of command -v uv;
  • every repository path in the configuration is absolute;
  • the JSON passes jq empty;
  • kgfegmcp-stdio-smoke still passes; and
  • Claude Desktop was fully quit and reopened.

Inspect Claude MCP logs on macOS

find "$HOME/Library/Logs/Claude" \
  -maxdepth 1 \
  -type f \
  -iname '*mcp*' \
  -print

Use the server traceback or client log to distinguish a launch failure from a connector UI problem before changing application code or graph packages.

No module named 'mcp.types'

Check the configured argument list and confirm it launches:

python -m kgfegmcp.mcpb_server

Next: First queries