Playground Sign in Start free

MCP Setup Guide

Ujeebu ships a native Model Context Protocol server that exposes our APIs as typed tools. Plug it into any MCP-compatible host and your agent gains web access in under a minute.

There is nothing to compile and no npx / Homebrew step. You have two ways to run it:

  • Hosted (recommended) - point your MCP host at our managed endpoint https://mcp.ujeebu.com/mcp and authenticate with your API key. Zero install, always up to date.
  • Docker (self-host) - run the server yourself from the ujeebu/ujeebu-mcp image. Good when you want it inside your own network or CI.

TIP - Skip the docs, use the wizard.

The fastest path is the interactive setup wizard at /mcp. It pre-fills your API key in every config block, gives Cursor and VS Code one-click install buttons, and updates every snippet live as you type. This page covers the same ground in long form for reference and bookmarking.

What you get

Twelve typed tools, each with a full JSON Schema so the agent picks the right one and validates parameters before the call. Scraping is split into focused variants so the model reaches for the exact output it needs:

Tool What it does
ujeebu_scrape_html Render a URL (JS execution, scrolling, custom JS) and return clean or raw HTML.
ujeebu_scrape_screenshot Full-page or partial screenshot of a URL (base64 image).
ujeebu_scrape_pdf Render a URL to PDF (base64).
ujeebu_scrape_json Scrape returning a full JSON envelope: headers, status, timing, plus html/screenshot/pdf.
ujeebu_scrape_extract Scrape with custom extract_rules (CSS/XPath) and get structured JSON back.
ujeebu_extract Clean article extraction: title, author, date, text, images, media, feeds.
ujeebu_card Fast article preview from meta tags (title, summary, author, image); lighter than full extraction.
ujeebu_serp Google results: web, images, news, videos, maps. Geo- and language-targetable.
ujeebu_markdown Convert any page to clean, LLM-optimized Markdown.
ujeebu_chatgpt Fetch a URL plus a prompt; the page goes to ChatGPT and the model's reply comes back.
ujeebu_gemini Same as ujeebu_chatgpt, routed through Gemini.
ujeebu_account Plan, quota, credits used, balance, and next billing date. Useful for budget-aware agents.

TIP - Five ways to scrape

The ujeebu_scrape_* family covers HTML, screenshot, PDF, a full JSON envelope, and rule-based extraction; the agent picks the variant that matches the output it wants. All twelve tools share the same key and budget.

Requirements

  • An MCP-compatible host (see supported hosts below).
  • An Ujeebu API key. Sign up free if you don't have one - 5,000 credits, no card.
  • For the Docker method only: Docker installed on the host.

Connect

Hosted (recommended)

Point your host at the managed endpoint and pass your key as a bearer token. Nothing to install:

{
  "mcpServers": {
    "ujeebu": {
      "url": "https://mcp.ujeebu.com/mcp",
      "headers": { "Authorization": "Bearer uj_live_..." }
    }
  }
}

Replace uj_live_... with your key from your dashboard. That's the whole setup - the tools appear after your host reloads.

Docker (self-host)

Run the server from the published image; the host launches it over stdio:

{
  "mcpServers": {
    "ujeebu": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "UJEEBU_KEY", "ujeebu/ujeebu-mcp"],
      "env": { "UJEEBU_KEY": "uj_live_..." }
    }
  }
}

docker pulls the image on first run. -i keeps stdin open (MCP talks over stdio); --rm cleans up the container when the host closes it. Pin a version with ujeebu/ujeebu-mcp:<tag> if you want reproducible builds.

Supported hosts

The blocks below use the hosted form. To self-host instead, swap the server entry for the Docker block above - everything else is identical.

Claude Desktop

Config file location

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Paste the JSON block above, save, then fully quit and reopen Claude Desktop. The tools appear under the hammer icon in the chat input.

Cursor

Config file location

  • Global: ~/.cursor/mcp.json
  • Per-project: .cursor/mcp.json

Same JSON shape. After saving, reload Cursor.

TIP - One-click install.

The wizard at /mcp generates a one-click install link that adds the server without editing files.

VS Code (1.95+)

Config file location

  • User-level: ~/.vscode/mcp.json
  • Workspace: .vscode/mcp.json (commit this if your team shares the config)

VS Code uses servers instead of mcpServers, and a URL server needs type: "http":

{
  "servers": {
    "ujeebu": {
      "type": "http",
      "url": "https://mcp.ujeebu.com/mcp",
      "headers": { "Authorization": "Bearer uj_live_..." }
    }
  }
}

For the Docker method, use "type": "stdio" with the command/args/env from the Docker block.

Windsurf

Config file location

~/.codeium/windsurf/mcp_config.json

Same shape as Claude Desktop / Cursor. After saving, reload Windsurf (Cmd-Shift-P → "Reload Window").

OpenAI Agents SDK

For the hosted endpoint, use the streamable-HTTP transport:

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="ujeebu",
        params={
            "url": "https://mcp.ujeebu.com/mcp",
            "headers": {"Authorization": "Bearer uj_live_..."},
        },
    ) as ujeebu:
        agent = Agent(
            name="researcher",
            instructions="Use web tools to answer accurately.",
            mcp_servers=[ujeebu],
        )
        result = await Runner.run(agent, "Find the top React libs by stars.")
        print(result.final_output)

Install the SDK with pip install openai-agents. To self-host, swap MCPServerStreamableHttp for MCPServerStdio with params={"command": "docker", "args": ["run","-i","--rm","-e","UJEEBU_KEY","ujeebu/ujeebu-mcp"], "env": {"UJEEBU_KEY": "..."}}.

Google Agent Development Kit (ADK)

The ADK wraps MCP via MCPToolset. Works with Gemini, Vertex, or any model the ADK supports.

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

ujeebu = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://mcp.ujeebu.com/mcp",
        headers={"Authorization": "Bearer uj_live_..."},
    ),
)

agent = Agent(
    name="researcher",
    model="gemini-2.5-pro",
    instruction="Use web tools to answer accurately.",
    tools=[ujeebu],
)

Install with pip install google-adk.

Custom MCP client

Any MCP-compatible host works. Hosted: connect to https://mcp.ujeebu.com/mcp over streamable HTTP with an Authorization: Bearer <key> header. Self-hosted: launch docker run -i --rm -e UJEEBU_KEY=<key> ujeebu/ujeebu-mcp and speak stdio MCP to it.

Per-key budgets

Set a per-session credit cap so a runaway loop can't drain your account. Hosted: add a X-Ujeebu-Budget header. Docker: add UJEEBU_BUDGET to env:

"env": {
  "UJEEBU_KEY":    "uj_live_...",
  "UJEEBU_BUDGET": "500"
}

The server tracks credits across all tool calls in the session and refuses further requests once the budget is exhausted. Useful for evals, demos, and agent-side cost controls.

Your first agent (5-minute walkthrough)

  1. Get a key. Dashboard → copy the key that starts with uj_live_.

  2. Connect a host. Paste the Hosted block into Claude Desktop's config (or use the wizard one-click for Cursor / VS Code). Fully restart the host.

  3. Confirm the tools loaded. In a new chat, ask:

    Use the Ujeebu scrape tool to fetch https://example.com and show me the title.

    The agent should call scrape and return the page title. If it says it has no web tools, the config didn't load - reload the host (Claude Desktop must be fully quit, not just closed).

  4. Do something real. Try a research task that chains tools:

    Search Google for "best open-source vector databases 2026", open the top 3 results, and summarise each in two sentences with a link.

    The agent uses serp to search, then extract (or scrape) on each result - all billed to your one API key, visible in the dashboard.

  5. Cap the spend. For unattended runs, add a budget (see Per-key budgets) so an agent loop can't overspend.

Troubleshooting

Agent doesn't see the tools. Confirm the host fully reloaded after editing the config (most hosts only read MCP config at startup). For Claude Desktop, fully quit - closing the window isn't enough.

Hosted endpoint won't connect. Check the URL is exactly https://mcp.ujeebu.com/mcp and the header is Authorization: Bearer <key> (no quotes around the key beyond the JSON string). Corporate proxies sometimes strip custom headers - test from an unproxied network.

Docker: docker: command not found or permission denied. Docker isn't installed or your user isn't in the docker group. On macOS some hosts don't inherit your shell PATH; give an absolute path: "command": "/usr/local/bin/docker".

UJEEBU_KEY missing or invalid. The key starts with uj_live_. Copy it from your dashboard exactly - no trailing whitespace.

Tool calls return 429. You've hit a rate limit or budget cap. Check usage in your dashboard.

Using DeepSeek, Kimi, Qwen, or other open-source models

The MCP server is model-agnostic - any framework that can connect to MCP can use it, regardless of which LLM is reasoning. The easiest path for non-Anthropic / non-OpenAI models is the OpenAI Agents SDK with the provider's OpenAI-compatible endpoint:

from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIChatCompletionsModel
from agents.mcp import MCPServerStreamableHttp

# Point the OpenAI client at any OpenAI-compatible provider:
#   DeepSeek:  https://api.deepseek.com/v1
#   Kimi:      https://api.moonshot.cn/v1
#   Qwen:      https://dashscope.aliyuncs.com/compatible-mode/v1
#   Groq:      https://api.groq.com/openai/v1
#   vLLM/Ollama: http://localhost:8000/v1
client = AsyncOpenAI(base_url="https://api.deepseek.com/v1", api_key="<PROVIDER_KEY>")

async with MCPServerStreamableHttp(
    name="ujeebu",
    params={"url": "https://mcp.ujeebu.com/mcp",
            "headers": {"Authorization": "Bearer <UJEEBU_KEY>"}},
) as ujeebu:
    agent = Agent(
        name="researcher",
        model=OpenAIChatCompletionsModel(model="deepseek-chat", openai_client=client),
        instructions="Use web tools to answer accurately.",
        mcp_servers=[ujeebu],
    )
    result = await Runner.run(agent, "Find the top React libs by stars.")
    print(result.final_output)

Same shape works for LangChain (langchain-mcp-adapters) and LlamaIndex (llama-index-tools-mcp) - only the framework changes.

What's next

  • The interactive setup wizard handles the prefill-and-paste flow, including one-click installers for Cursor and VS Code.
  • Browse the API reference to see what each tool returns in detail.