# OpenServe for Agents: tool reference

Endpoint: https://www.openserve.com/api/v1/mcp
Auth: `Authorization: Bearer os_sk_…` (a workspace API key) or an OAuth 2.1
access token. Every tool runs against one workspace, as the person who made
the grant, with what their role allows today.

Legend: R = read. W = records a reversible row or files a draft for a
person's approval. Scopes marked (owner) can only be granted by the
workspace owner.

## Visitors — scopes `identity:read`, `identity:write`

- `list_website_visitors` R: companies that visited the workspace's sites,
  with pages read and whether it looked like buying, plus the workspace's own
  known people who came back. Never names a person from an IP. Input: `days`
  (1 to 90).
- `list_audiences` R: saved audiences.
- `get_retention` R: list growth, returning readers, win-back results.
- `get_visitor_settings` R: the autopilot and network settings.
- `create_audience` W: save an audience. Kinds: `visited` (a page or section),
  `intent` (pricing, demo or contact), `known` (gave their email and visited),
  `lapsed` (known, not back in N days), `company` (visits from named domains).
- `sync_audience_to_channel` W: keep an audience current on the workspace's
  own Meta or Google ad account. The first send waits for a person.
- `add_company_to_crm` W: file a company that visited in the last 90 days.
- `update_visitor_settings` W: the visitors autopilot and the network opt-out.

## CRM — scopes `crm:read`, `crm:write`

- `search_companies` R, `list_deals` R, `get_deal` R
- `create_company` W, `create_deal` W, `move_deal` W, `log_follow_up` W

## Ads — scopes `ads:read`, `ads:write` (owner)

- `list_campaigns` R, `get_campaign` R, `list_ad_moves` R, `list_ad_accounts` R
- `apply_ad_move` W: files the move for approval; it is not applied by you.
- `dismiss_ad_move` W, `set_campaign_autopilot` W
- `propose_budget` W: a proposal, counted against the grant's daily paid
  budget.

## Email — scopes `email:read`, `email:draft`

- `list_email_lists` R, `get_email_performance` R, `get_newsletter_ads` R
- `draft_email` W: files a draft. A person sends it.

## Social — scopes `social:read`, `social:draft`

- `list_social_pages` R, `get_social_traffic` R
- `draft_social_post` W: files a draft. A person posts it.

## Sites — scopes `site:read`, `site:write`, `site:publish` (owner)

- `site_read` R, `site_patch` W
- `site_publish` W: the one write that reaches the public web, behind an
  owner-granted scope, a daily limit and a moderation gate.

## Analytics — scope `analytics:read`

- `get_analytics` R: realtime, retention, paths, monetization, interface.

## Brand — scope `brand:read`

- `get_brand_kit` R: voice, colours, fonts, logo. Null when none exists; say
  so and write plainly rather than inventing a voice.

## Agents — scopes `agents:read`, `agents:run`

- `list_agents` R, `get_run` R
- `ask_genius` W, `brief_team` W, `run_flow` W: these spend the person's
  plan, as chat does.

## Approvals — scope `approvals:read`

- `request_approval` W, `get_approval` R, `list_approvals` R

## Collectives — scopes `collective:read`, `collective:write`

- `list_collective_memberships` R, `find_collective_members` R,
  `list_collective_introductions` R
- `propose_collective_partner` W, `request_collective_introduction` W,
  `decide_collective_partnership` W

## Reading — scope `content:read`

- `search_content` R: published articles by title. Metadata and the
  canonical link only.
- `check_content_access` R: whether the person may read an article, without
  serving or charging. `outcome` is `allow`, `offer` or `deny`.
- `read_content` R: the text with publisher, canonical link, rights and a
  signed source receipt. Without access: the free opening, `complete: false`
  and offers. The only `purpose` a grant covers is `personal_assistance`.
- `get_content_usage` R: for a publisher, agent reads of their own posts.

The same reads are available over REST: `POST /api/v1/open/search`,
`POST /api/v1/open/access/evaluate`, `GET /api/v1/open/resources/{id}`.
Discovery: https://www.openserve.com/.well-known/openserve.json

## Errors

- HTTP 401: missing, revoked or expired grant, or its creator is no longer
  an owner or admin of the workspace.
- HTTP 429: rate limited.
- A tool result with `isError: true` carries a message you can show the
  person, for example a spent daily cap.
- A tool your grant does not carry answers "Unknown tool".