MCP

Jina AI Remote MCP Server

CLI version A remote Model Context Protocol (MCP) server that provides access to Jina Reader, Embeddings and Reranker APIs with a suite of URL-to-markdown, web search, image search, and embeddings/reranker tools:

Optional tools work without an API key but have rate limits. For higher rate limits and better performance, use a Jina API key. You can get a free Jina API key from https://jina.ai

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.

[!NOTE] The server uses Streamable HTTP transport (MCP spec 2025-03-26). The /sse endpoint is kept as an alias for backward compatibility. See FAQ for details.

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 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}"
      ]
    }
  }
}

For Claude Code:

[!WARNING] Upgrading from /sse? If you previously added with --transport sse, remove it first with claude mcp remove -s user jina, then re-add using the command below.

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}"]

Tool Filtering before Registering

Every MCP tool requires the LLM to pre-allocate tokens in its context window for the tool's name, description, and schema. For LLMs with limited context windows, registering all 22 tools can consume significant space before any actual work begins.

By filtering tools server-side via query parameters on the endpoint URL (/v1?...), excluded tools are never registered with the MCP client. The client and LLM never see them, saving context window for what matters.

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 parallel tools (saves ~4 tools worth of context tokens):

{
  "mcpServers": {
    "jina-mcp-server": {
      "url": "https://mcp.jina.ai/v1?exclude_tags=parallel",
      "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_images,deduplicate_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 the thinking and tool calling continue, once you hit the context window limit, the AI starts losing track of the beginning of the task. That's how it gets trapped in this rolling context window.

The solution is to load the model with enough context length to contain the full tool calling chain and thought process.

I can't see all tools.

Some MCP clients have local caching and do not actively update tool definitions. If you're not seeing all the available tools or if tools seem outdated, you may need to remove and re-add the jina-mcp-server to your MCP client configuration. This will force the client to refresh its cached tool 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 " // spaces OK in env vars
  }
},

Cursor shows a red dot on this MCP status

Likely a UI bug from Cursor, but the MCP works correctly without any problem. You can toggle off/on to "restart" the MCP if you find the red dot annoying (fact is, since you are using this as a remote MCP, it's not a real "server restart" but mostly a local proxy restart).

My LLM never uses some tools

Assuming all tools are enabled in your MCP client but LLM still never uses some tools or favors some over others, this is pretty common when an LLM is trained with a specific set of tools. For example, we rarely see parallel_* tools being used organically by LLMs unless they are explicitly instructed to do so. Some research says LLMs must be trained to use parallel_*. Models like Qwen3-Next natively prefer to call the singleton version but with multiple queries in an array to achieve parallelism (which our MCP also support now). Either way, in Cursor, you can add the following rule to your .mdc file:

…

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 and parallel_read_url.

Items are kept whole in their original order while they fit. The first item that does not fit is cut to a prefix that does, and anything after it is dropped. A short [jina-mcp] ... note is appended saying what was truncated or omitted, so the model knows it is looking at a partial document rather than a complete one. At least one item always survives, even if that item alone is over budget.

The server deliberately aims under the limit rather than exactly at it. It has to: the server counts tokens with cl100k while the client counts with its own tokenizer, the cut is a proportional character estimate, and the client measures the serialized JSON payload rather than the raw text. On top of the token budget the server therefore enforces a hard ceiling of 3 bytes per allowed token, which holds regardless of tokenizer for both ASCII prose (~3.6 bytes/token) and CJK (~3 bytes/token). A rejected response d