Journely Markets MCP server

Plug Journely's markets data into any MCP-aware AI tool — Claude Desktop, Cursor, Cline, Continue, Goose, or your own agent. Same data as the REST API, same authentication, same rate limits.

What is MCP? Model Context Protocol is an open standard for connecting LLM agents to external tools. If you use Claude Desktop or Cursor, MCP is how you give them new abilities — like calling Journely's data — without writing custom integration code.

Endpoint

POST https://api.journely.me/api/v1/journely/mcp

Transport: Streamable HTTP (the current MCP transport, as defined in spec revision 2025-06-18). Stateless — every request is independent. Authentication is your personal access token, the same one used by the REST API.

Available tools

Tool name	Returns
`get_markets`	API catalog — supported countries, currencies, asset types, symbol counts, upcoming trading holidays. Start here.
`get_macro_indicators`	Macro indicator panel (GDP, inflation, labor, etc.) for a country, optionally filtered by category.
`get_macro_forecast`	Forward-looking macro forecasts for a country.
`get_macro_calendar`	Upcoming economic events (FOMC, CPI, NFP, GDP) with previous / forecast / consensus / actual.
`get_sectors`	Sector roll-up with country index P/E + per-sector P/E median, ROE, growth, margins. The rotation-decision endpoint.
`get_stock_overview`	Per-ticker overview, valuation, business model, performance.
`get_stock_statements`	Income statement, balance sheet, or cash flow for a ticker.
`get_stock_technicals`	Technical-indicator panel (MA, RSI, MACD, etc.) for a ticker.

Top-down workflow: get_markets → get_macro_indicators → get_macro_calendar → get_sectors → get_stock_overview → get_stock_statements / get_stock_technicals.

Each tool returns the same JSON payload its REST counterpart does — see the REST reference for response shapes. Your client receives both a text content block (for older MCP clients) and a structured structuredContent object (preferred where supported).

Setup — Claude Desktop

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Remote HTTP MCP servers are configured under mcpServers with a url entry.

{
  "mcpServers": {
    "journely-markets": {
      "url": "https://api.journely.me/api/v1/journely/mcp",
      "headers": {
        "Authorization": "Bearer jrn_live_YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Claude Desktop. The 6 Journely tools become available to Claude inside any chat — ask for "AAPL's latest financials" or "the US inflation outlook" and it will call the appropriate tool.

Setup — Cursor

Cursor configures MCP servers via ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root.

{
  "mcpServers": {
    "journely-markets": {
      "url": "https://api.journely.me/api/v1/journely/mcp",
      "headers": {
        "Authorization": "Bearer jrn_live_YOUR_TOKEN_HERE"
      }
    }
  }
}

Setup — Cline / Continue / Goose

All MCP-compliant clients accept the same Streamable HTTP server URL + Authorization header pair. Consult your client's docs for where to put the JSON snippet above; the values are identical.

Raw protocol — curl example

If you're building a custom client or just want to verify connectivity:

curl -X POST https://api.journely.me/api/v1/journely/mcp \
  -H "Authorization: Bearer jrn_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_macro_indicators",
      "arguments": { "country": "US", "category": "prices" }
    }
  }'

Rate limits

Only tools/call consumes quota. initialize, tools/list, and ping are free, so your client's handshake never burns daily calls. Limits match the REST API:

Plan	Daily	Hourly
Free	100	30
Pro	5,000	500
Max	50,000	5,000

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. On denial: HTTP 200 + JSON-RPC error code -32001 with retry_after_seconds in the data field.

Errors

JSON-RPC error codes follow the spec; server-defined codes are in the -32000 range:

Code	Meaning
`-32700`	Parse error — body wasn't valid JSON.
`-32600`	Invalid Request — missing `jsonrpc` field or malformed envelope.
`-32601`	Method not found — unknown JSON-RPC method or tool name.
`-32602`	Invalid params — missing required arguments.
`-32603`	Internal server error.
`-32001`	Rate limit exceeded. Inspect `data.retry_after_seconds`.
`-32002`	Tool execution failure (transient backend error).

Authentication failures (missing / invalid token) are surfaced as HTTP 401 before the JSON-RPC dispatcher runs — clients that ignore HTTP status codes will see no response body for these.

Business-logical errors from the tools themselves (unknown country, missing ticker, etc.) come back as a normal tool result with isError: true — the model sees them and can react.

Spec reference: modelcontextprotocol.io/specification · Protocol version 2025-06-18