Skip to main content

MCP Setup

The CIAK MCP server is a local binary that exposes 7 tools to AI assistants through the Model Context Protocol. Your IDE launches the MCP server as a subprocess and communicates with it over stdio. Behind the scenes, the MCP server talks to the CIAK cloud to serve results.

Prerequisites​

  1. CIAK CLI and MCP server installed — see Getting Started.
  2. A scanned project — run ciak init and ciak scan --embeddings in your project directory.
  3. Verify both binaries are available:
ciak --version
ciak-mcp-server --version

IDE Configuration​

The MCP server takes no command-line arguments. It is configured entirely via environment variables and auto-detects project context from its working directory or ~/.ciak/. The only argument-free command is sufficient for most setups.

Windsurf​

Add a CIAK MCP server entry to your Windsurf MCP configuration file. Open Settings → MCP Servers or edit the configuration JSON directly:

{
  "mcpServers": {
    "ciak": {
      "command": "ciak-mcp-server"
    }
  }
}

If ciak-mcp-server is not in your PATH, use the full path to the binary:

{
  "mcpServers": {
    "ciak": {
      "command": "/usr/local/bin/ciak-mcp-server"
    }
  }
}

Cursor​

In Cursor, open Settings → MCP and add a new server:

{
  "mcpServers": {
    "ciak": {
      "command": "ciak-mcp-server"
    }
  }
}

Claude Desktop​

Edit your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "ciak": {
      "command": "ciak-mcp-server"
    }
  }
}

VS Code (with MCP extension)​

If you are using a VS Code extension that supports MCP, add the server to your workspace .vscode/settings.json:

{
  "mcp.servers": {
    "ciak": {
      "command": "ciak-mcp-server"
    }
  }
}

Logging to a file​

By default, the MCP server logs to stderr. To redirect logs to a file instead (useful when debugging IDE integrations), set these environment variables in your IDE config:

{
  "mcpServers": {
    "ciak": {
      "command": "ciak-mcp-server",
      "env": {
        "CIAK_LOG_TO_FILE": "true",
        "CIAK_LOG_DIR": "/path/to/logs"
      }
    }
  }
}

The log file will be written as mcp_server.log inside the specified directory.

Multi-Project Setup​

If you work on multiple projects, configure one MCP server instance per project using the CIAK_PROJECT_PATH environment variable:

{
  "mcpServers": {
    "ciak-frontend": {
      "command": "ciak-mcp-server",
      "env": {
        "CIAK_PROJECT_PATH": "/home/user/frontend"
      }
    },
    "ciak-backend": {
      "command": "ciak-mcp-server",
      "env": {
        "CIAK_PROJECT_PATH": "/home/user/backend"
      }
    }
  }
}

Alternatively, many MCP tools pass a project_path parameter per request, so a single server can serve multiple projects if configured to resolve project paths dynamically.

Verifying the Setup​

Once configured, your AI tool should show CIAK's 7 tools as available:

ToolDescription
search_codeNatural language code search
analyze_symbolsSymbol search with filtering
vector_searchSemantic similarity search
optimize_contextContext optimization for AI tasks
get_related_contextDiscover related files
analyze_relationshipsDependency and relationship analysis
search_knowledgeQuery the knowledge base

Try asking your AI assistant something like:

"Search for functions that handle authentication"

It should use the search_code tool and return results from your codebase.

Troubleshooting​

Project not found / no results​

Make sure you have run ciak scan in your project first:

cd /path/to/your-project
ciak init
ciak scan --embeddings

Then verify the project was initialized:

ls -la .ciak/

MCP server not starting​

  1. Check that the ciak-mcp-server binary is executable and in your PATH.
  2. Try running it manually from your project directory to see error output:
cd /path/to/your-project
ciak-mcp-server
  1. Check your CIAK_API_URL is reachable if you have customized it.

Search tools return Cannot POST /api/query/process or Cannot POST /api/symbols/search​

Those routes belong to the Rust CIAK API service, not the NestJS backend or frontend hosts. If you override CIAK_API_URL, point it to:

export CIAK_API_URL="https://api.ciak.at"

Do not use https://user-api.ciak.at, https://app.ciak.at, or https://admin.ciak.at for MCP search tools.

Search tools return Missing or invalid Bearer token​

That means the Rust API is reachable, but it is running in JWT-only cloud mode. Current CIAK cloud deployments use:

  • CIAK_API_URL=https://api.ciak.at
  • CIAK_AUTH_URL=https://user-api.ciak.at

If you are self-hosting, set CIAK_AUTH_URL to the backend host that serves /auth/login/license and /auth/jwks.

Search tools return Missing route permission for requested endpoint​

If the request reaches https://api.ciak.at and authenticates successfully, but the API still returns:

{"error":"Missing route permission for requested endpoint","error_code":"route_scope_missing_permission"}

the user JWT is valid but does not contain the expected route permissions. One confirmed cause is an account created through the signup flow without the default user role being assigned. After updating the backend to a build that repairs missing roles on signup/login, sign in again and retry the MCP tool.

No vector search results​

Vector search requires embeddings. Re-scan with the --embeddings flag:

ciak scan --embeddings

Tools not appearing in the AI client​

  • Restart the AI client after changing MCP configuration.
  • Check the client's MCP logs for connection errors.
  • Ensure the configuration JSON is valid (no trailing commas, correct paths).

Next Steps​