MCP tool services
Everything the Agent can do enters through an MCP server: five services built by FewBox, plus any third-party server you register yourself. This page covers what each one provides, how to register them, and how pricing works.
First, there is no marketplace here
No service discovery, no one-click install. On startup, thia-agent reads mcp.servers[] in
agentic.yaml, connects to them one by one, and puts the tools reported by successfully
connected servers into the model's tool table. Three conclusions follow:
- Installing a service does not mean it is usable - you must register an entry in the YAML.
- The tool name is the contract, not the
id. At runtime the server is found by tool name (heartbeat RSS fetching usesfindServerForTool('fetch_feed')), so theidcan be anything, but renaming a tool breaks compatibility. - Registered but the service is not running only affects that one entry (there is a connection failure line in the log); the other servers keep working.
Five built-in services
| Service | Tools | What it does | External credentials |
|---|---|---|---|
mcp-vision |
generate_image · edit_image · blending_image |
Text-to-image, single-image editing, multi-image blending (Seedream / Gemini) | At least one set of model keys |
mcp-perception |
perceive_images · compare_framing |
Describe what is in an image; measure whether a rewritten image lost the original framing | Ark key |
mcp-motion |
generate_video |
Generate video from text / image / reference material | Ark key |
mcp-fetch |
fetch_url · fetch_feed |
Fetch web pages; read RSS/Atom and decide new vs. old by entry id | None |
mcp-analysis |
list_databases · run_sql |
Read-only SQL: list the queryable databases first, then query | Database connection string |
Ports and probes are in Services and ports; environment variables and the deployment
manifest are in the mcp-* section of manual per-service deployment.
One sentence per tool
generate_image- Text-to-image. Depending on model capability, produces one image at a time or a batch on the same theme.edit_image- Single-image edit: give a reference image plus instructions, get back the edited image.blending_image- Blend two or more reference images; the upper limit is set by the model (10-14 for current models).perceive_images- Hand one or more images to a vision model with a prompt and get back a description/analysis.compare_framing- Does not use a vision model: feature matching computes the camera displacement and zoom between two images and returnsstable/drift/undeterminedin about a second. Good for confirming rewrites like "only the furniture changed, the camera did not move."generate_video- Text-to-video, first-frame / first-and-last-frame to video; multimodal models can also take reference images/video/audio. The call waits until generation finishes.fetch_url- Fetch a public URL and turn it into readable text (format: rawkeeps the original text).fetch_feed- Read RSS/Atom and return the results entry by entry. Decide new vs. old by entry id, not by title - if someone edits a title once, it will be reported again.list_databases/run_sql- List databases and get anidfirst, then run one read-only SELECT against that database. The connection itself is read-only; write statements are rejected.
How to register
All five services use an HTTP transport (the image sets MCP_TRANSPORT=http and exposes only
POST /mcp), so the address must include /mcp:
mcp:
resilience: # global default; each server can override
callTimeoutMs: 300000 # image/video generation are long tasks; the default 30s is not enough
retry: { maxRetries: 3 }
servers:
- id: 'fewbox-remote-vision'
name: 'FewBox Remote Vision'
enabled: true
transport:
type: 'streamable-http'
url: '${VISION_ENDPOINT}' # http://mcp-vision/mcp
pricing: # see the next section; omitted = 0 USD per call
kind: image
models:
<model name>: { perUnit: { metric: imageCount, rate: 0.035 } }
resilience:
callTimeoutMs: 300000 # you can also override the global value above with the same value
Three transports:
type |
Required fields | When to use |
|---|---|---|
streamable-http |
url (optional headers) |
Standalone services inside the cluster. All five mcp-* are this type |
sse |
url (optional headers) |
Third-party servers that only support the old SSE protocol |
stdio |
command (optional args / env / cwd) |
Local development; the server runs as a child process of the agent |
⚠️ Prefer
streamable-httpin a cluster. Astdioserver is a child process inside the agent Pod, andnpx -yneeds to download the package on every cold start - the Pod must have outbound network access and a writable temporary directory. Being able to install it does not mean it starts every time.
⚠️ The factory
agentic.yamlin the repository registers only vision / motion / perception / analysis, notfetch. If you installmcp-fetch, you must add an entry yourself (tool namesfetch_url/fetch_feed); otherwise a routine with a fetch source logsRoutine runtime fetch NOT availableat startup and falls back to the model round every round.
Adding a third-party server
Same servers[], same shape:
- id: 'tavily'
name: 'Tavily Search'
transport:
type: 'streamable-http'
url: 'https://<third-party address>/mcp'
headers: { Authorization: 'Bearer ${TAVILY_API_KEY}' }
pricing: { pricePerCall: 0.008 } # quoted price per search
Pricing rules
Prices are not in the service; they are in this YAML. A service only reports usage (image
count, token count) in the result's _meta["com.fewbox/usage"]; the agent takes that usage and
applies the YAML rules to compute the charge. Pick one of three:
| Mode | Syntax | Used for |
|---|---|---|
| Fixed per call | pricePerCall: 0.008 |
Search, fetch, and other one-price-per-call tools |
| Usage-based | perUnit: { metric: imageCount, rate: 0.035 } plus optional multipliers |
Images per image, video per token |
| Per token | tokens: { inputTokenPricePerMillion, outputTokenPricePerMillion } |
Vision-model answers and similar |
- When one server serves multiple models (vision does), use
models:to write prices per model name; for tools without a model (such ascompare_framing), usetools:per tool name. - No match means 0, and the record is marked
unpriced. This is deliberate: a new model will not silently inherit another model's price. For free tools, write{ pricePerCall: 0 }as well, so "free" and "forgot to configure" stay distinguishable. - If you write
models/tools, you cannot also write a price at the top level; configuration validation rejects it outright (the price would be ambiguous).
Prices are in USD; user charges are converted to credits by billing.creditCostUsd.
Roles and heartbeat
Two fields control "who can use it" and "when it can be used"; both go on the server entry:
requiredRoles: ['ADMIN'] # only sessions with the ADMIN role can see/call it; omitted = everyone
availableInRoutines: false # do not expose this server's tools in heartbeats
requiredRolesis fail-closed: if none of the session's roles match, the entire server's tools are removed from the tool table.availableInRoutines: falseis usually for two kinds: very expensive ones (image, video - they should not run on their own with nobody watching), and ones the heartbeat does not need (every round is a new session, so you pay for the tool definitions for nothing).
mcp-analysis ships configured this way - read-only SQL is available only to admins and never
runs automatically in a heartbeat.
What happens if you do not register
| Symptom | Cause |
|---|---|
| The model has no idea the tool exists | Not registered, enabled: false, or the URL cannot connect (the tool table only takes tools from successfully connected servers) |
| The routine falls back to the model round every round | fetch_feed is not on any registered server |
| A regular user cannot see a tool | requiredRoles is in effect; this is also the quickest way to confirm permissions are configured correctly |
| Image/video generation always times out | resilience.callTimeoutMs is left at the default 30s; long tasks need 300s |
After registering, send one conversation from thia-web; the log should show each server
connecting successfully one by one - this is the only check that proves "the tools really
reached the model." A green probe or a page that opens does not count.