cortex-research-mcp 0.1.0

MCP connector for the Cortex Research gateway (TimescaleDB, Motherduck, Neo4j, Qdrant)

Cortex Research MCP Connector

A one-command connector that gives your AI IDE (Claude Code, Cursor, Codex) direct, no-repo-clone access to the Cortex research data sources — TimescaleDB, Motherduck, Neo4j, and Qdrant — via the production gateway at https://wasif-cortex.fly.dev. No manual Python environment, no cloning this repo. Just two steps.

What you need

• A Cortex collaborator API key (cortex_...). Ask Wasif to add your email to the collaborator key list if you don't have one yet.
• macOS/Linux/Windows with a terminal.

Step 1 — install uv (one-time, ~10 seconds)

uv is a fast Python package/tool runner. If you don't already have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

(Windows: see https://docs.astral.sh/uv/getting-started/installation/)

That's it — you do NOT need to separately install Python, create a virtual environment, or clone this repository.

Step 2 — add the connector to Claude Code

claude mcp add cortex-research --env CORTEX_API_KEY=cortex_xxxxxxxx -- \
  uvx --from cortex-research-mcp cortex-research-mcp

Replace cortex_xxxxxxxx with your actual key. That's the entire setup. uvx downloads and runs the connector in an isolated, cached environment — nothing to maintain, nothing to update manually.

Interim note (pre-PyPI-publish): until this package is published to PyPI (see "Publishing to PyPI" below), Wasif will hand you a built wheel file (cortex_research_mcp-0.1.0-py3-none-any.whl) instead. Use:

claude mcp add cortex-research --env CORTEX_API_KEY=cortex_xxxxxxxx -- \
  uvx --from /absolute/path/to/cortex_research_mcp-0.1.0-py3-none-any.whl cortex-research-mcp

Once published, drop the /absolute/path/to/...whl and use the plain package name shown in Step 2 — same command shape either way.

Alternative: .mcp.json snippet

Drop this into your project's .mcp.json (or global MCP config):

{
  "mcpServers": {
    "cortex-research": {
      "command": "uvx",
      "args": ["--from", "cortex-research-mcp", "cortex-research-mcp"],
      "env": {
        "CORTEX_API_KEY": "cortex_xxxxxxxx"
      }
    }
  }
}

Environment variables

Variable	Required	Default	Purpose
CORTEX_API_KEY	Yes	none	Your collaborator API key, sent as X-API-Key
CORTEX_API_URL	No	https://wasif-cortex.fly.dev	Gateway base URL override

Never commit your CORTEX_API_KEY to git or paste it into shared files.

Tools exposed

Tool	Purpose
query_timescale(sql_query, limit=200)	Read-only SELECT against TimescaleDB
query_motherduck(sql_query, limit=200)	Read-only SQL against the Motherduck panel
query_neo4j(cypher_query, limit=100)	Read-only Cypher against the Neo4j knowledge graph
query_qdrant(query_text, limit=10)	Semantic search against Qdrant vector memory
write_timescale(sql_query)	Write/insert into sandbox research_* tables (server-enforced allowlist)
publish_finding(name, cagr, max_dd, sharpe, logic_desc, parameters=None)	Publish a finding to the team promotion queue
get_northstar()	Fetch the current research NORTHSTAR.md
whoami()	Confirm your API key works and see your collaborator identity

Troubleshooting

• 401 Unauthorized: your CORTEX_API_KEY is missing, invalid, or expired. Double-check the env var is set in your MCP server config, or ask Wasif to verify/add your key.
• 403 Forbidden: your key is valid but not authorized for that specific action (e.g., a write outside the sandbox allowlist). Ask Wasif to check your collaborator role.
• Server won't start: confirm uv/uvx is on your PATH (uvx --version).

For maintainers: building and testing locally

This directory is a standard installable Python package (cortex-research-mcp, console entry point cortex-research-mcp, import package mcp_cortex).

cd research/sdk/mcp_cortex
uv build                     # produces dist/*.whl
uvx --from dist/cortex_research_mcp-0.1.0-py3-none-any.whl cortex-research-mcp

Local tool-listing smoke test (no network, no API key needed):

uv run --with dist/cortex_research_mcp-0.1.0-py3-none-any.whl python3 -c "
import asyncio
from mcp_cortex.server import mcp
async def main():
    tools = await mcp.list_tools()
    print([t.name for t in tools])
asyncio.run(main())
"

This should print all 8 tool names.

Publishing to PyPI (recommended final step — needs Wasif's PyPI account)

Once published, collaborators can drop the wheel path entirely and use the plain uvx --from cortex-research-mcp cortex-research-mcp command shown in Step 2. Publishing requires a PyPI account with the cortex-research-mcp name registered (or scoped, e.g. wasif-cortex-research-mcp, if the bare name is taken) — this is Wasif's account/credentials, not something a collaborator can do themselves.

cd research/sdk/mcp_cortex
uv build
uv publish   # prompts for a PyPI API token (or set UV_PUBLISH_TOKEN)

After publishing, no code change is needed here — uvx --from cortex-research-mcp will resolve from PyPI automatically.