# AGENTS.md - ONLINESVR quickstart for AI agents

ONLINESVR is a marketplace of ready-to-run tools for AI. Published tools called Capabilities let agents and developers run OCR, media generation, document conversion, device control, model chat, and other digital work on demand. This document tells an AI agent how to connect to ONLINESVR, how to run its tools, and where to read about the platform without connecting at all.

## Start here

Three kinds of session read this document. Pick the one you are in.

- Only a link to this document, or a task that needs a Capability. Connect the MCP server below, then follow "Run Capabilities with MCP". A session that arrives with no task in it is here to get set up, so treat the setup as the work rather than as a question to put to the user.
- A question about ONLINESVR — what it does, what Capabilities exist, what it costs. Answer it from "ONLINESVR vocabulary" below, the Store at `https://onlinesvr.com/store.md`, the plans at `https://onlinesvr.com/pricing.md`, and the documentation pointers near the end. None of the setup applies.
- Code that keeps running after this session ends — a server, a scheduled job, a product feature. Skip interactive MCP setup and use the REST API with an API token, described under "Add ONLINESVR to an existing app".

### Connect over MCP

If ONLINESVR MCP tools are already available, use them and skip the rest of this section. An empty tool list is not a verdict that MCP is unavailable here: it means the connection is not set up yet, and setting it up is your work.

Your own client's MCP documentation is the source of truth for how a server gets added here — a setup command such as `mcp add`, a configuration file with a schema of its own, a connector you can drive. Read it before you write anything, then add the server and tell the user what you added. A setup command is the surer path, because it writes whatever shape this client expects.

There is one remote server, `https://mcp.onlinesvr.com`, reached over Streamable HTTP. Most clients express that as:

```json
{
  "mcpServers": {
    "onlinesvr": {
      "url": "https://mcp.onlinesvr.com",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}
```

Treat that as the common shape rather than the universal one. Clients differ on the top-level key, on the field that names the URL, and on how a transport is declared — a client that reads a plain `url` as an SSE endpoint wants its streamable-HTTP field instead, since this server speaks Streamable HTTP only. Your client's documentation names the exact keys. The live configurator at `https://mcp.onlinesvr.com` carries per-client instructions.

`tools/list` can discover published tools without a key. `tools/call` requires a platform API Key as `Authorization: Bearer <API_KEY>` plus Capability grants and quota. Missing keys get HTTP 401. Create a free account at `https://onlinesvr.com/en/sign-up` (no credit card required on the free plan), then create an API Key in Console: `https://console.onlinesvr.com`.

The user's steps are the ones that need them: creating or pasting an API Key into the MCP config, and restarting or reconnecting the client when it cannot pick up a new server on its own. Ask for those, then carry on with the task they already gave you instead of having them repeat it.

You are connected when you can list or call an ONLINESVR tool. A configuration shown in the chat is a suggestion, not a connection. A server that connects but lists no tools usually needs approving, trusting, or enabling in this client, which its documentation covers under the same MCP pages.

Setup can genuinely fail: your client may have no mechanism for adding a server, its configuration may sit out of your reach, or the API Key may be missing or declined. Say which step failed, then take one of the paths under "Choose another integration path".

## ONLINESVR vocabulary

These words mean something specific on ONLINESVR and appear in tool names, responses, and pages below. Use them as defined here rather than by their ordinary English meaning.

- Capability — A packaged, runnable unit on the platform that takes structured input, performs a task, and produces structured output or artifacts. It is not an AI agent or a person: on ONLINESVR, "Capability" always means this kind of program and is always capitalized when naming the product concept.
- Capability Run / Task — One execution of a Capability. Long work returns a `task_id`; poll until the status is terminal, then fetch results or artifacts.
- ONLINESVR Store — The marketplace of Capabilities at `https://onlinesvr.com/store` (Markdown index: `https://onlinesvr.com/store.md`).
- ONLINESVR Console — The web UI at `https://console.onlinesvr.com` (also reachable via `https://api.onlinesvr.com/console/`), where a human manages runs, keys, and billing.
- MCP Gateway — Streamable HTTP entry at `https://mcp.onlinesvr.com`. Published Store Capabilities appear as typed MCP tools on the same Gateway runtime used by Console and REST.
- API Key — Bearer credential for MCP `tools/call` and REST. Store it in an environment variable or secret manager; never put it in source, chat logs, or URLs.

Further platform terms are introduced in `https://docs.onlinesvr.com/llms.txt` as documentation expands.

## Run Capabilities with MCP

The MCP tool list is dynamic. Inspect it with `tools/list`, then follow these steps. If this session began with nothing but a link to this document, ask the user what they want to automate while the key is being added: their answer is the search subject for step 1.

1. Find a Capability: list tools, or open the Store at `https://onlinesvr.com/store` / `https://onlinesvr.com/store.md`. Prefer the Capability that matches the platform or job the user named — for example OCR, Seedance image/video, document conversion, device screen control, or model chat.
2. Inspect input: read the tool schema from MCP (or the Capability detail page). Build arguments from the schema rather than guessing field names.
3. Run it: call the tool with validated input. Before the first paid run of a session, tell the user the Capability's pricing model (when known) and your cost estimate and wait for a go-ahead — once, not before every call.
4. Wait for completion: short tools may return results inline. Longer work returns a task / order id and a non-terminal status — poll until the status is terminal (`succeeded`, `failed`, `timed_out`, or equivalent).
5. Get the data: fetch dataset items, artifacts, or download URLs from the completed task. Do not invent results.
6. Finish explicitly: success means the run reached a success terminal status and the requested data or artifact was returned. On failure, report the status message and stop or correct the input before retrying.

Running Capabilities and reading private run data requires authentication. Discovering published tools can be done without a key via `tools/list`.

## Explore without running

This path answers research questions — which Capabilities exist, what documentation says. Use it when no Capability is going to run in this session, or when an API Key is not available yet.

- Browse Store HTML: `https://onlinesvr.com/en/store`
- Store Markdown index: `https://onlinesvr.com/store.md`
- Pricing Markdown: `https://onlinesvr.com/pricing.md`
- MCP configurator (no key needed to read setup): `https://mcp.onlinesvr.com`
- Docs index: `https://docs.onlinesvr.com/llms.txt`

## Choose another integration path

| Situation | Use |
| --- | --- |
| Interactive MCP-capable agent | Remote MCP + API Key — the default path above |
| Application, script, server, or other headless workflow | REST API + API Key |
| Client supports only local MCP servers | Local stdio bridge that forwards to `https://mcp.onlinesvr.com` with the same Bearer header |
| Coding agent performing a reusable workflow | Follow docs at `https://docs.onlinesvr.com` and this quickstart |

### API token

Sign up at `https://onlinesvr.com/en/sign-up`, then create a token in Console integrations / API keys. Send it in the header:

```
Authorization: Bearer <ONLINESVR_API_KEY>
```

Store tokens in an environment variable or secret manager. Keep them out of source files, chat logs, command output, and URLs.

### Run over HTTP

Platform HTTP APIs live under `https://api.onlinesvr.com`. Marketplace and identity surfaces use `/api/v1/...` paths. Prefer MCP for agent sessions; use REST when you are writing durable application code. Exact route shapes and OpenAPI evolve with the platform — check `https://docs.onlinesvr.com` and `https://onlinesvr.com/openapi.json` when present.

Authentication failures return `401` or `403`. Follow the response details: provide a valid Bearer credential and ensure the key has grants for the Capability.

## Add ONLINESVR to an existing app

Use the REST API with an API Key for code that outlives the chat session. State pricing and get a go-ahead before the first paid run. Prefer environment variables:

```bash
export ONLINESVR_API_KEY=...
```

JavaScript/TypeScript sketch:

```typescript
const res = await fetch("https://api.onlinesvr.com/api/v1/marketplace/capabilities", {
  headers: { Authorization: `Bearer ${process.env.ONLINESVR_API_KEY}` },
});
```

Python sketch:

```python
import os, urllib.request
req = urllib.request.Request(
    "https://api.onlinesvr.com/api/v1/marketplace/capabilities",
    headers={"Authorization": f"Bearer {os.environ['ONLINESVR_API_KEY']}"},
)
```

For MCP from application code, open a Streamable HTTP client to `https://mcp.onlinesvr.com` with the same Bearer header.

## Documentation for agents

- Agent quickstart (this file): `https://onlinesvr.com/agents.md` (also `https://onlinesvr.com/AGENTS.md`)
- Site index for LLMs: `https://onlinesvr.com/llms.txt`
- Docs index: `https://docs.onlinesvr.com/llms.txt`
- Specific docs page as Markdown: append `.md` when advertised, for example `https://docs.onlinesvr.com/platform.md`
- MCP configurator: `https://mcp.onlinesvr.com`
- Help: `https://help.onlinesvr.com`
- Status: `https://status.onlinesvr.com`

## Resources

Machine-readable contracts, for an agent that needs to inspect a capability rather than read prose about it.

- MCP configurator and per-client setup: `https://mcp.onlinesvr.com`
- Store Markdown: `https://onlinesvr.com/store.md`
- Pricing Markdown: `https://onlinesvr.com/pricing.md`
- Auth notes: `https://onlinesvr.com/auth.md`
- OpenAPI (when published): `https://onlinesvr.com/openapi.json`
- Robots / sitemap: `https://onlinesvr.com/robots.txt`, `https://onlinesvr.com/sitemap.xml`