Claude Desktop Setup Guide - Cortex AI MCP Integration¶

Last Updated: 2026-02-26
For: Cortex AI Developers

Overview¶

This guide will help you integrate Cortex AI's MCP servers with Claude Desktop, giving you access to 52 powerful tools: - 44 infrastructure tools (Proxmox, pfSense, Grafana, Vault, Loki, etc.) via MCP Gateway - 8 code search tools (semantic search, repo navigation, git operations) via cortex-context

Quick Start¶

Step 1: Export Configuration¶

Go to https://app.cortex.emshvac.co/admin/mcp-config
Log in with your Cortex AI credentials
Click "Copy Configuration" button
The configuration is now in your clipboard

Step 2: Install cortex-context¶

Download and install the cortex-context binary:

# Download cortex-context (get the latest release)
curl -L https://github.com/your-org/cortex-context/releases/latest/download/cortex-context-darwin-amd64 -o /usr/local/bin/cortex-context

# Make it executable
chmod +x /usr/local/bin/cortex-context

# Verify installation
cortex-context --version

Step 3: Set Environment Variables¶

Add these to your shell profile (~/.zshrc or ~/.bashrc):

# MCP Gateway Authentication
export MCP_GATEWAY_TOKEN="your-oauth2-token-here"  # Get from Zitadel

# Voyage AI (for cortex-context)
export VOYAGE_API_KEY="pa-KhHT3HdKVG-9K2EJTOLZwVv-51ozmlhDoujZelUTzFT"

Then reload your shell:

source ~/.zshrc  # or source ~/.bashrc

Step 4: Configure Claude Desktop¶

Open 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
Paste the configuration you copied from Step 1
Save the file

Step 5: Restart Claude Desktop¶

Close and reopen Claude Desktop. You should now see the MCP tools available!

Getting Your OAuth2 Token¶

Option 1: Via Zitadel UI¶

Go to https://auth.cortex.emshvac.co
Log in with your credentials
Navigate to Personal Access Tokens
Click "Create New Token"
Select scopes:
mcp:read (required - read-only access)
mcp:proxmox:read (optional - view containers)
mcp:grafana:read (optional - query metrics)
mcp:loki:read (optional - search logs)
Copy the token and set it as MCP_GATEWAY_TOKEN

Option 2: Via CLI (Advanced)¶

# Using curl to get a token
curl -X POST https://auth.cortex.emshvac.co/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=your-email@example.com" \
  -d "password=your-password" \
  -d "client_id=cortex-mcp" \
  -d "scope=mcp:read"

Verifying Installation¶

Test cortex-context¶

# Index your codebase (run this in your project directory)
cd ~/your-project
cortex-context index .

# Test search
cortex-context search "authentication handler"

Test in Claude Desktop¶

Open Claude Desktop and try:

Can you search for authentication code in the codebase?

If configured correctly, Claude will use the search tool from cortex-context.

Available Tools¶

Infrastructure Tools (via MCP Gateway)¶

Category	Tools	Description
Proxmox	8 tools	Container management, VM operations
pfSense	6 tools	Firewall rules, DNS, DHCP
Grafana	5 tools	Metrics, dashboards, alerts
Vault	4 tools	Secrets management
Loki	4 tools	Log aggregation and search
Traefik	3 tools	Load balancer, routing
Zitadel	3 tools	Identity and access
Others	11 tools	Various infrastructure

Code Tools (via cortex-context)¶

Tool	Description	Example Use
`search`	Semantic code search	"Find authentication logic"
`read`	Read file with line ranges	"Show auth.go lines 50-100"
`repo_map`	Project structure overview	"What's the project structure?"
`read_symbol`	Find function definition	"Show AuthHandler implementation"
`related`	Find related code	"What calls this function?"
`git_diff`	View git changes	"What changed in this branch?"
`git_status`	Check git status	"What files are modified?"
`commit_search`	Search commits	"Find auth-related commits"

Troubleshooting¶

Issue: "MCP server not responding"¶

Solution: Check that environment variables are set:

echo $MCP_GATEWAY_TOKEN
echo $VOYAGE_API_KEY

Issue: "cortex-context: command not found"¶

Solution: Verify cortex-context is in your PATH:

which cortex-context
# Should output: /usr/local/bin/cortex-context

Issue: "Authentication failed"¶

Solution: 1. Verify your OAuth2 token is valid 2. Check token scopes include mcp:read 3. Try generating a new token

Issue: "No search results from cortex-context"¶

Solution: Index your codebase first:

cd ~/your-project
cortex-context index .

Issue: "Gateway timeout"¶

Solution: Check if the MCP Gateway is running:

curl -I http://192.168.11.115:8080/health

Advanced Configuration¶

Custom cortex-context Configuration¶

Create ~/.config/cortex-context/config.yaml:

search:
  top_k: 20
  rerank:
    enabled: true
    model: "rerank-2"
    top_n: 10
  rse:
    enabled: true
    max_segment_chunks: 5

qdrant:
  host: "192.168.11.130"
  grpc_port: 6334

voyage:
  api_key: "${VOYAGE_API_KEY}"
  model: "voyage-4"

Selective Tool Access¶

If you only want code tools (no infrastructure):

{
  "mcpServers": {
    "cortex-code": {
      "command": "/usr/local/bin/cortex-context",
      "args": [],
      "env": {
        "VOYAGE_API_KEY": "${VOYAGE_API_KEY}",
        "QDRANT_HOST": "192.168.11.130",
        "QDRANT_GRPC_PORT": "6334"
      }
    }
  }
}

Security Best Practices¶

Never commit tokens to git repositories
Use environment variables for sensitive data
Rotate tokens regularly (every 90 days)
Request minimal scopes - only what you need
Revoke unused tokens in Zitadel

Support¶

Documentation: https://app.cortex.emshvac.co/admin/docs
MCP Config Export: https://app.cortex.emshvac.co/admin/mcp-config
Issues: Contact the Cortex AI team

Next Steps¶

✅ Complete this setup guide
Try using Claude Desktop with MCP tools
Explore the available tools
Share feedback with the team
Help improve the documentation