Sahara DIP MCP

Local stdio MCP server for querying Sahara DIP data through the existing REST API.

Quick Start with Codex

After the package is published, add it to Codex with one command:

codex mcp add sahara_dip \
  --env CRYPTO_KB_API_KEY=ckb_live_xxx \
  -- npx -y @saharaai/[email protected]

The published package contains the production Portal MCP gateway route and uses X-Sahara-DIP-Key automatically. Product keys are blocked from direct DIP data-plane access by default. CRYPTO_KB_API_BASE_URL and CRYPTO_KB_API_KEY_HEADER remain available as advanced overrides for local, test, or legacy-compatible configurations.

Confirm that Codex saved the server:

codex mcp get sahara_dip

Restart Codex after adding or changing the server. The API key is passed only to the MCP child process. Treat the Codex config containing it as a secret.

Local Development

cd crypto-kb-mcp
npm ci
npm run build

Required environment variable:

export CRYPTO_KB_API_KEY="ckb_live_xxx"

Optional:

# Override the built-in Portal Gateway for local or test environments.
export CRYPTO_KB_API_BASE_URL="http://localhost:8280/api/mcp/dip"
export CRYPTO_KB_TIMEOUT_MS="15000"
# Required with a Portal Gateway URL override; direct DIP remains an explicit
# legacy/test-only configuration.
export CRYPTO_KB_API_KEY_HEADER="X-Sahara-DIP-Key"

API Key Access

Existing legacy Crypto KB API keys remain compatible. New productized MCP keys should be created by the backend internal key endpoint after the Portal or admin bridge has checked the user's entitlement.

Expected scopes for both Free and Paid product MCP keys are the complete allow-listed MCP set: dip.api.read, dip.mcp.call, dip.data.free, and dip.data.premium. Both tiers can call every published MCP tool. The Portal gateway applies separate configurable per-minute limits for the free and paid tiers; the data scopes do not restrict individual MCP tools.

Unclassified DIP routes remain unavailable to product keys, and the gateway continues to charge credits and call DIP with its trusted upstream credential.

Credit accounting is per logical MCP tool invocation. The published Gateway combines the internal DIP calls for search_crypto_knowledge and get_project_profile under one reservation; partial search results are returned when available and the Gateway settles only the proportional successful share. An all-failed service call is refunded, while insufficient balance is rejected before DIP is called.

MCP responses are intentionally bounded for agent context usage. Search results contain summaries instead of full documents, recent events include only matching summaries, and market history defaults to 10 rows per section with a maximum of 50. Market analysis excludes raw candles and reports freshness from the latest source candle timestamp.

Codex MCP Config

Codex reads MCP servers from ~/.codex/config.toml or a trusted project's .codex/config.toml. The equivalent configuration for the published package is:

[mcp_servers.sahara_dip]
command = "npx"
args = ["-y", "@saharaai/[email protected]"]

[mcp_servers.sahara_dip.env]
CRYPTO_KB_API_KEY = "ckb_live_xxx"

For a non-production or local Gateway, add the explicit override:

CRYPTO_KB_API_BASE_URL = "https://gcp-dev.saharaa.info/developer/api/mcp/dip"
CRYPTO_KB_API_KEY_HEADER = "X-Sahara-DIP-Key"

During development, run the TypeScript entrypoint directly from this repository:

[mcp_servers.sahara_dip]
command = "npm"
args = ["--prefix", "/absolute/path/to/crypto-kb-mcp", "run", "dev"]

[mcp_servers.sahara_dip.env]
CRYPTO_KB_API_BASE_URL = "http://localhost:3000"
CRYPTO_KB_API_KEY = "ckb_live_xxx"

After changing config, restart the MCP client so the new environment variables are picked up.

Tools

• search_crypto_knowledge: searches projects, docs, and news.
• get_project_profile: resolves a project by symbol, name, slug, or token address.
• get_market_packet: fetches unified spot and perpetual market data for a symbol.
• get_market_analysis: fetches current spot/perpetual structure and screening signals for a symbol.
• get_recent_events: fetches recent analyzed events matching a token, project, or keyword.

Example Prompts

• "Use Crypto KB to search for recent BTC knowledge base entries."
• "Get the market packet for ETHUSDT and summarize the latest futures structure."
• "Fetch current market analysis for SOL and list the strongest spot and perpetual signals."
• "Find recent listing-related events for Binance."

Error Handling

The MCP server maps backend auth failures into stable client-facing errors:

• AUTHENTICATION_FAILED for HTTP 401. Check CRYPTO_KB_API_KEY.
• AUTHORIZATION_FAILED for HTTP 403. The key is valid but missing the MCP call scope or the request is outside the published gateway surface.
• UPSTREAM_HTTP_ERROR for other non-2xx backend responses.
• UPSTREAM_REQUEST_FAILED for network, timeout, or fetch failures.

Verification

npm test
npm run typecheck
npm run build
npm run smoke:stdio
npm run smoke:failure
npm pack --dry-run

smoke:stdio launches the compiled server through the MCP SDK's stdio client, completes the MCP handshake, and verifies the published tool list without calling the backend. It can also validate a packed artifact, for example node scripts/stdio-smoke.mjs npx -y --package ./saharaai-sahara-dip-mcp-0.1.2.tgz sahara-dip-mcp.

smoke:failure starts a loopback-only fault server and verifies bounded MCP tool errors for invalid authentication, missing scopes, backend 500, socket disconnect, and timeout. It then proves that the same MCP process recovers when the upstream becomes healthy. The fixture also rejects API key leakage in tool responses and server stderr.

Before publishing a release candidate, build the tarball twice and retain its manifest and checksum outside the repository:

ARTIFACT_OUTPUT_DIR=/absolute/path/to/release-candidate \
EXPECTED_MCP_PACKAGE_SPEC=@saharaai/[email protected] \
npm run verify:release

The command refuses a dirty crypto-kb-mcp worktree by default. It verifies the package name/version, dist/index.js bin entry, file allowlist, repeatable npm integrity and SHA-256, then writes the .tgz and .manifest.json files. Setting ALLOW_DIRTY_RELEASE_ARTIFACT=true is only for testing the verifier while it is being developed; such a manifest must not be published.

Use smoke:backend when a backend and an API key are available. It performs the same MCP handshake and calls search_crypto_knowledge through the MCP protocol:

# For the published production package, omit CRYPTO_KB_API_BASE_URL so the
# package's built-in Portal Gateway route is exercised.
CRYPTO_KB_API_KEY=ckb_live_xxx \
npm run smoke:backend

# For a local or non-production Gateway, provide the explicit route and header.
CRYPTO_KB_API_BASE_URL=http://127.0.0.1:8180/api/mcp/dip \
CRYPTO_KB_API_KEY_HEADER=X-Sahara-DIP-Key \
CRYPTO_KB_API_KEY=ckb_live_xxx \
npm run smoke:backend

To test a packed artifact instead of the local build, pass the package command after the script name:

CRYPTO_KB_API_KEY=ckb_live_xxx \
node scripts/backend-smoke.mjs npx -y --package ./saharaai-sahara-dip-mcp-0.1.2.tgz sahara-dip-mcp

Backend smoke path:

CRYPTO_KB_API_BASE_URL="http://localhost:3000" \
CRYPTO_KB_API_KEY="ckb_live_xxx" \
npm run build