Jina AI Remote MCP Server

A remote Model Context Protocol (MCP) server for the Jina Reader, Search, Embeddings and Reranker APIs:

Usage

[!WARNING] Some clients do not support env variable, so you may need to replace ${JINA_API_KEY} below to a hardcoded real API key jina_xxx.

For client that supports remote MCP server:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}" // optional
      }
    }
  }
}

For Claude Code:

claude mcp add -s user --transport http jina https://mcp.jina.ai/v1 \
  --header "Authorization: Bearer ${JINA_API_KEY}"

For OpenAI Codex: find ~/.codex/config.toml and add the following:

[mcp_servers.jina-mcp-server]
command = "npx"
args = [
    "-y",
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization: Bearer ${JINA_API_KEY}"]

For client that does not support remote MCP server yet, you need mcp-remote a local proxy to connect to the remote MCP server.

{
  "mcpServers": {
    "jina-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.jina.ai/v1",
        "--header",
        "Authorization: Bearer ${JINA_API_KEY}"
      ]
    }
  }
}

Available tools

Optional tools work without an API key at rate limits. Use a key for higher limits. Free keys: https://jina.ai

Tool Filtering before Registering

Registering a tool costs context tokens for its name, description and schema whether or not it is called. With 12 tools, that budget is spent before the first request.

Filtering server-side through query parameters on the endpoint URL (/v1?...) excludes tools before registration, so the client never sees them.

Query Parameters

Available Tags

Precedence

Filters are applied in this order (highest to lowest priority):

1. exclude_tools - Always excludes specified tools
2. exclude_tags - Excludes tools in specified tags
3. include_tools - Includes specified tools
4. include_tags - Starts with only tools in specified tags

Examples

Exclude the rerank and utility tags:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tags=rerank,utility",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Only include search and read tools:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?include_tags=search,read",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Exclude specific tools:

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tools=search_ssrn,search_images",
      "headers": {
        "Authorization": "Bearer ${JINA_API_KEY}"
      }
    }
  }
}

Troubleshooting

I got stuck in a tool calling loop - what happened?

This is a common issue with LMStudio when the default context window is 4096 and you're using a thinking model like gpt-oss-120b or qwen3-4b-thinking. As thinking and tool calling continue, the run hits the context limit, the model loses the start of the task, and it loops.

Load the model with enough context length to hold the whole tool-calling chain.

I can't see all tools.

Some MCP clients have local caching and do not actively update tool definitions. If tools are missing or look outdated, remove and re-add the jina-mcp-server to force a refresh of the cached definitions. In LMStudio, you can click the refresh button to load new tools.

Claude Desktop says "Server disconnected" on Windows

Cursor and Claude Desktop (Windows) have a bug where spaces inside args aren't escaped when it invokes npx, which ends up mangling these values. You can work around it using:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://mcp.jina.ai/v1",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <JINA_API_KEY>" // spaces OK in env vars
  }
},

Cursor shows a red dot on this MCP status

Likely a Cursor UI bug. The MCP works. Toggling off/on clears the dot; on a remote MCP that restarts the local proxy, not a server.

My LLM never uses some tools

If all tools are enabled but the model still ignores some, that is expected: models call the tools they were trained on. Some research says LLMs must be trained to use a tool family. In Cursor, add this rule to a .mdc file:

---
alwaysApply: true
---

When you are uncertain about knowledge, or the user doubts your answer, always use Jina MCP tools to search and read best practices and latest information. Use search_arxiv and read_url together when questions relate to theoretical deep learning or algorithm details. Use search_ssrn for social sciences, economics, law, and finance research. search_web, search_arxiv, and search_ssrn cannot be used alone - always follow with read_url on the result URLs. One read_url call can take up to 5 URLs at once.

Why is my content truncated?

Claude Code, Claude Desktop, and Cursor enforce a fixed 25k token limit on MCP tool responses. To stop these clients from rejecting a large response outright, this server applies a token guardrail to read_url.

Items are kept whole, in order, while they fit. The first that does not fit is cut to a prefix that does, and later items are dropped. A [jina-mcp] ... note records what was truncated or omitted, so a partial document is marked partial. At least one item always survives, even one over budget.

The server targets below the limit. It counts tokens with cl100k, the client with its own tokenizer, the cut is a proportional character estimate, and the client measures the serialized JSON payload instead of the raw text. It therefore also enforces a ceiling of 3 bytes per allowed token, which holds across tokenizers for ASCII prose (~3.6 bytes/token) and CJK (~3 bytes/token). Cutting short loses part of the content. A rejected response loses all of it.

Any client can set its own budget with max_tokens on the endpoint URL (for example https://mcp.jina.ai/v1?max_tokens=50000), and max_tokens=0 disables truncation entirely. Clients with configurable limits, such as OpenAI Codex (tool_output_token_limit), are otherwise left alone.

Several queries or URLs in one call

search_web, search_arxiv, search_ssrn and read_url take a string or an array on query / url. An array runs every item concurrently in a single round trip. search_images takes one query at a time.

{ "url": ["https://react.dev/reference/react/useState",
          "https://docs.python.org/3/library/functions.html"],
  "question": "what does the hook or built-in return" }

Arrays cap at 5 entries, enforced by the schema. withAllLinks, withAllImages, question, chunk_size, topk, ocr and page are set once for the whole array, not per entry: every URL in the call gets the same