Cortex AI MCP - Quick Start Guide¶

Get Claude Desktop working with Cortex AI in 5 minutes!

🚀 One-Command Installation¶

macOS¶

Open Terminal and run:

curl -fsSL https://app.cortex.emshvac.co/install-mcp.sh | bash

Windows¶

Open PowerShell as Administrator and run:

irm https://app.cortex.emshvac.co/install-mcp.ps1 | iex

What This Does¶

The installer will:

✅ Download and install cortex-context (code search tool)
✅ Set up environment variables
✅ Configure Claude Desktop automatically
✅ Verify the installation

Total time: ~2 minutes

What You'll Need¶

Before running the installer, get your MCP Gateway Token:

Go to https://auth.cortex.emshvac.co
Log in with your Cortex AI credentials
Navigate to Personal Access Tokens
Click "Create New Token"
Select scope: mcp:read
Copy the token

The installer will ask for this token.

After Installation¶

1. Restart Claude Desktop¶

Close and reopen Claude Desktop to load the new configuration.

2. Test It Out¶

Ask Claude:

Can you search for authentication code in the codebase?

If configured correctly, Claude will use the MCP tools to search your code!

3. Try More Commands¶

Show me the project structure

Find all functions that handle user login

What files have been modified recently?

Search the logs for errors in the last hour

What You Get¶

52 Total Tools¶

Code Tools (8) - via cortex-context: - search - Semantic code search - read - Read files - repo_map - Project structure - read_symbol - Find definitions - related - Find related code - git_diff - View changes - git_status - Git status - commit_search - Search commits

Infrastructure Tools (44) - via MCP Gateway: - Proxmox (8 tools) - Container management - pfSense (6 tools) - Firewall, DNS - Grafana (5 tools) - Metrics, dashboards - Vault (4 tools) - Secrets - Loki (4 tools) - Logs - And 17 more...

Troubleshooting¶

"Command not found: cortex-context"¶

Solution: Restart your terminal to reload PATH.

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

# Windows
# Close and reopen PowerShell

"Authentication failed"¶

Solution: Check your token is set correctly.

# macOS/Linux
echo $MCP_GATEWAY_TOKEN

# Windows
$env:MCP_GATEWAY_TOKEN

If empty, set it manually:

# macOS/Linux
export MCP_GATEWAY_TOKEN="your-token-here"

# Windows
$env:MCP_GATEWAY_TOKEN = "your-token-here"

"No search results"¶

Solution: Index your codebase first.

cd ~/your-project
cortex-context index .

Still Having Issues?¶

Check the full setup guide: https://app.cortex.emshvac.co/admin/docs
View your configuration: https://app.cortex.emshvac.co/admin/mcp-config
Contact the Cortex AI team

Manual Installation¶

If you prefer to install manually, visit:

https://app.cortex.emshvac.co/admin/mcp-config

This page provides: - Step-by-step instructions - Configuration file to copy - Environment variables to set - Download links for all components

Advanced Usage¶

Index Multiple Projects¶

# Index your main project
cd ~/projects/backend
cortex-context index .

# Index another project
cd ~/projects/frontend
cortex-context index .

Custom Configuration¶

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

search:
  top_k: 30
  rerank:
    enabled: true
    top_n: 15

Check What's Indexed¶

cortex-context stats

Security Notes¶

✅ All tokens are stored as environment variables (not in config files)
✅ cortex-context runs locally (no data sent to external servers except Voyage AI for embeddings)
✅ MCP Gateway uses OAuth2 authentication
✅ All requests are logged for audit

Best Practices: - Never commit tokens to git - Rotate tokens every 90 days - Use minimal scopes (start with mcp:read) - Revoke unused tokens

Next Steps¶

✅ Complete installation
✅ Test with Claude Desktop
📚 Read the full documentation
🎯 Explore all 52 tools
💡 Share feedback with the team

Links¶

Quick Install: https://app.cortex.emshvac.co/admin/mcp-config
Documentation: https://app.cortex.emshvac.co/admin/docs
Get Token: https://auth.cortex.emshvac.co
Support: Contact Cortex AI team

Questions? Visit https://app.cortex.emshvac.co/admin/docs for detailed documentation.