Connection checklist
Work through these first. Each refusal from the service names its reason, and most come down to one of them.
The key is set where the harness starts. This prints the word set and keeps the key itself hidden.
echo ${BALTOR_SERVICE_TOKEN:+set}The endpoint is exact.
https://baltor.ai/mcp, over streamable HTTP.The protocol version matches. The service serves
2025-11-25and2026-07-28.The key is current. Keys stay active until they expire or you revoke them. Create a new one on Keys and connections.
The harness restarted after the change. Harnesses read their settings when they start.
The service is working. The status page reads it live each time you open it.
A refused connection
- The service answers with a list of versions.
- Your client named a protocol version outside the two the service serves. Choose
2025-11-25or2026-07-28in your harness settings, or update the harness. - The key is refused.
- Revoked and expired keys are refused on their next request. Create a key on Keys and connections and set it again in your environment.
- Sign-in asks you to try again later.
- Sign-in allows 30 refused attempts from one network address in 60 seconds. Wait a minute, check your password and confirm your email.
- An app asks for access through OAuth.
- The consent page names the app and its return destination. Check both, then allow the scopes you want; the connection works within them.
Searches that come back short
- Fewer results than you expected.
- A search returns the references your account may read, up to 50. Describe the step in other words, switch between exact words and close spellings, or include community items.
- The request is refused for size.
- A request holds up to 64 KiB. Shorten the query or split the work.
- Operations wait their turn.
- Each account runs 4 operations at once. The rest run as earlier ones finish.
A refused download
- The checksum differs.
- The download names the checksum you expect, and the Workspace saves a download once its bytes match. A new checksum means the item changed: search again and choose its current version. Updates and withdrawals
- The file declares effects.
- Reading files is the default. A file that declares more effects downloads once the step declares them too, with
Baltor-Step-Effects. - The body is large.
- Bodies up to 16 KiB arrive inline; larger ones come through
/api/v1/download, up to 1 MiB each. - The item belongs to another plan.
- Harness Files come with Pro. Public Good files come with any account. Compare plans
When the service has a problem
- A page says Something broke on our side.
- The page names what failed and shows a reference code on its own line. Quote that reference when you write. See the error pages
- Feed files answer 503.
- Feed files answer 503 while a library update runs, and answer again once it finishes.
- An unchanged feed answers 304.
- That is the expected answer when you send the last ETag in
If-None-Match: your copy is current. - Your harness reports the service out of reach.
- Open the status page. It reads the service live each time you open it.
After a timeout
If an action times out, first check whether it happened. Reconcile an uncertain outcome before repeating an external action. Files that arrived stay on your computer, and your usage record shows each download with its time.
Write to the operator
When the checks pass and an answer still puzzles you, write to the operator: Baltor.AI, info@baltor.ai, United States. Include the time, your harness, the protocol version, the key's name and any reference code, and keep the key itself private.
Need a hand? Status, the connection checklist and the operator's email address are on one page.
Get support