MCP Server Plugin Documentation

The MCP (Model Context Protocol) Server Plugin is provided through the C3 Package mcpServer, and includes C3 Types, Seed Data, Metadata, and dependent packages. This package enables developers to quickly enable their applications as an MCP server.

Copy link to this section

Dependencies

Copy link to this section

Key C3 AI Types in this package

Copy link to this section

Key files in this package

The package is structured in the following manner:

mcpServer/
└── src/
    ├── mcp/
    │   └── toolEngine/
    ├── prompt/
    ├── tools/
    └── ui/

Copy link to this section

Package-level changelogs

• Version 4.0

Copy link to this section

C3 MCP Server — Quick Start

Goal: run your app as an MCP server and connect to it from VS Code or Cursor.

Copy link to this section

1) Start your app as an MCP server

Copy link to this section

Prerequisites

• Your app declares a dependency on the mcpServer package.
• Your app is running (the MCP endpoints are served by your running app).
• It’s strongly recommended your app exposes at least one tool so the MCP server does something useful.
  • Example:

# Create your own tool
test_type = c3.GenaiCore.Tool.C3Method.TestType
c3_add_tool = c3.GenaiCore.Tool.C3Method.createFromMethodName(test_type, "add")

# For this tool we need to ensure the flag `enabledInMcpServer` is set to True
# and upsert the tool into your application
c3_add_tool.withEnabledInMcpServer(True).upsert()

Copy link to this section

Base endpoints

Your app should expose MCP under these paths (replace placeholders with real values):

• MCP root:
  https://<cluster-name>/<env>/<app>/mcp
• VS Code installer:
  https://<cluster-name>/<env>/<app>/mcp/vscode
• Cursor installer:
  https://<cluster-name>/<env>/<app>/mcp/cursor
• JSON config (for project-scoped setup):
  https://<cluster-name>/<env>/<app>/mcp/json
• MCP server endpoint:
  https://<cluster-name>/<env>/<app>/mcp/server

Tip: You’ll need an auth cookie when using the JSON config. The header looks like:

{
  "url": "https://<cluster-name>/<env>/<app>/mcp/server",
  "headers": {
    "Authorization": "c3Bearer <TOKEN>"
  }
}

Copy link to this section

2) Connect from your IDE

You can connect from VS Code or Cursor. The installer links above will auto-fill most fields for you.

Copy link to this section

A) VS Code

Open: https://<cluster-name>/<env>/<app>/mcp/vscode

• VS Code 1.102.2 and earlier

  1. A prompt appears to install the MCP server (named C3 Server - <env>/<app> by default).
  2. Click Install to complete setup (installed globally).

• VS Code 1.102.3 and later

  1. An install page opens inside VS Code.
  2. Click Install.
  3. After installation you can find the entry at:
     • Code/User/mcp.json, or
     • via command palette: “MCP: Open User Configuration.”

Copy link to this section

Project-scoped setup (optional)

If you prefer per-repo settings rather than global:

1. Open: https://<cluster-name>/<env>/<app>/mcp/json
2. Copy the returned JSON (includes the url and required Cookie header).
3. Save it as {project-root}/.vscode/mcp.json.

This keeps the server config local to the repository and avoids modifying your global user config.

Copy link to this section

B) Cursor

Open: https://<cluster-name>/<env>/<app>/mcp/cursor

1. Allow the browser to open Cursor.
2. Cursor shows an install screen with the server URL/name prefilled.
3. Click Install. The server will appear in Cursor’s MCP settings.

Note: Use a recent Cursor build (1.2.1+ recommended) for the smoothest install flow.

Copy link to this section

3) Verify the connection & use tools

• VS Code

  1. Open Copilot Chat.
  2. Go to the Tools tab and pick one of your app’s tools.
  3. When prompted, click Continue/Allow to grant the tool permission.
  4. Run a quick command and confirm you see a successful result.

• Cursor

  1. Open a chat.
  2. When a tool is invoked, click Accept/Allow.
  3. Confirm the tool returns results without errors.

If your app exposes no tools, the MCP connection works but there’s nothing useful to invoke. Expose at least one tool to test end-to-end.

Copy link to this section

4) Troubleshooting

• Installer page stuck (VS Code):
  Close and reopen VS Code, then revisit the installer URL for your version.

• 401/403 errors when using project-scoped JSON:
  Ensure the Authorization header is present and contains a valid c3Bearer token for the target environment.

• Server not found / 404:
  Confirm your app is running and the base path responds at
  https://<cluster-name>/<env>/<app>/mcp.

• Nothing shows in Tools:
  Double-check your app actually registers tools with the MCP server.

• Per-repo config not taking effect (VS Code):
  Make sure the file path is exactly {project-root}/.vscode/mcp.json and your workspace is opened at the project root.

Copy link to this section

5) Quick checklist

1. Add dependency: mcpServer is included in your app.
2. Run your app: MCP is served at /mcp.
3. Install in IDE:
   • VS Code: visit /mcp/vscode (or use /mcp/json → .vscode/mcp.json).
   • Cursor: visit /mcp/cursor.
4. Approve tools: Allow tool usage when prompted.
5. Smoke test: Call one tool and verify a successful response.