MCP server

The Lovely Router MCP server lets an agent plan a task, find a tool, read its input schema, run it and read the results on its own. It also exposes the browser agent. Every call goes through the same API as REST, so billing, limits and errors are identical.

Connect your client#

Create a key in API keys first. A key with a spend limit is a good idea for agents: see control cost.

claude mcp add --transport http lovely-tools https://lovelyrouter.com/mcp \
  --header "Authorization: Bearer $LOVELY_API_KEY"

{
  "mcpServers": {
    "lovely-tools": {
      "type": "http",
      "url": "https://lovelyrouter.com/mcp",
      "headers": { "Authorization": "Bearer ${LOVELY_API_KEY}" }
    }
  }
}

Test the connection#

The server speaks plain JSON-RPC, so you can call it with cURL. This lists the tools it exposes:

curl https://lovelyrouter.com/mcp \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Tools the server exposes#

Two tools search and read the web. The server tells the agent to use them for anything it needs to look up or read, and to keep the browser agent for pages it has to interact with.

Two tools make images with GPT Image 2.5, or GPT Image 2 when 2.5 is unavailable, billed like the Images API: $0.04 per image, any size, nothing when it fails.

Five tools cover the data catalog. The server tells the agent to plan with suggest_tools (or search_tools for a single tool), read the schema with get_tool, then call run_tool.

Four tools drive the browser agent. It is for pages the agent has to interact with: logins, forms, multi-step flows. To read what a page says, web_fetch is faster and cheaper. The browser runs in the cloud and can't open localhost or private addresses.

Each browser argument is described in the browser agent guides: modes, structured output, logins and profiles, files and human in the loop. Passwords and one-time codes are not sent through MCP: the agent uses vault secrets by name, and a person sends codes through the API.

What the tools return#

Answers are written for a model to read, and kept short, because agents cut off or spill long tool results:

• web_search returns numbered results with the title, site, date, URL and summary. web_fetch returns the page in parts of about 12,000 characters, with the run_id and offset that read on.
• run_tool and get_run return a line with the run id, tool, status, result count and charge, then one line per result with empty fields left out and long text cut. That fits about 12,000 characters per answer, and the last line says how to get the rest: get_run with an offset, or fields to keep only the keys you need. The full JSON stays available from GET /v1/tools/runs/{run_id}.
• The other tools return the same JSON as the matching REST endpoint, as text: POST /v1/tools/suggest, POST /v1/tools/discover and GET /v1/tools/{id}.
• Errors come back as a tool result with isError: true and the message, so the agent can adjust. When run_tool rejects an input, the answer lists the tool's input fields and an example.
• generate_image and get_image return a line with the job id, size, file size and charge, the download link and a curl command for it. The job is the same as one made with POST /v1/images/jobs, so it shows in your logs and its image is also at GET /v1/images/jobs/{id}/content with your key for 7 days.
• Long runs. run_tool waits up to 50 seconds, because most clients give up on a tool call after about a minute. A run still going after that comes back as Still running. Call get_run with this run id to get the results. followed by the run. A client that allows longer tool calls can add ?wait= to the server URL (10 to 280 seconds).

Without a key#

suggest_tools, search_tools and get_tool work without a key, so an agent can browse the catalog before you connect a key. run_tool, get_run and the browser tools return an authentication error until you add one.

What an agent session looks like#

Ask Claude Code, with the server connected: "Find vegan restaurants in Austin and tell me what their reviews complain about." A typical session:

1. Plan. The agent calls suggest_tools with the task. The plan says to run google-maps-places first, then google-maps-reviews, for an estimated $0.0585 at the default caps.
2. Read the schema. It calls get_tool with {"tool": "google-maps-places"} to see the input fields.
3. Find the places. It calls run_tool:
   JSON

   {
     "tool": "google-maps-places",
     "input": {"searchTerms": ["vegan restaurant"], "location": "Austin, Texas, USA"},
     "max_results": 10
   }

   Ten places come back with their placeIds. Cost: $0.00075 + 10 × $0.000238 = $0.00313.

4. Get the reviews. It calls run_tool again with the place ids, five reviews per place:
   JSON

   {
     "tool": "google-maps-reviews",
     "input": {"placeIds": ["ChIJ...", "ChIJ..."], "maxReviews": 5, "reviewsSort": "newest"},
     "max_results": 50
   }

   Fifty reviews come back. Cost: 50 × $0.000675 = $0.03375.

5. Answer. The agent reads the reviews and summarizes the complaints. The whole task cost about $0.08, and both runs appear in Tools in your dashboard.

Prices above are today's. get_tool and suggest_tools always return the live price.

Control cost#

• Give the agent its own key with a spend limit. A run that could take the key past its limit is refused with 402 before anything is charged. See API keys.
• Ask for max_results on every run. The cap bounds the cost: per-call fee plus per-result fee times max_results. Without it, the tool's default applies. A line in your prompt or project instructions works: "Always set max_results, and ask me before any run that can cost more than $0.50."
• Plan first. suggest_tools and get_tool are free and show the price, so the agent can check a run's maximum cost before it starts.
• Review spend. Every run and its charge is listed in Tools. Failed runs that return nothing cost nothing.

At most 10 runs can be in progress on your account at once. See Run a tool for how runs are billed.