Ona MCP server

1. What it is

MCP, the Model Context Protocol, is a standard way for an AI assistant to use outside tools. Ona's MCP server is one of those tools: once you connect an assistant, it can look up your Ona conversations, read their notes and transcripts, read your to-dos and daily recaps, and, if you allow it, add a to-do.

The assistant only sees your own account, and only what the permission you gave allows. This page is the reference for the server. For a short introduction, see MCP in Ona.

2. Requirements

MCP is part of Ona Pro. On any other plan the server still answers initialize and tools/list, but every tool call is refused with the error plan_required.

You also need an assistant that supports remote MCP servers over Streamable HTTP. The Ona web app has a setup button for Claude and for Cursor, and any other MCP client can use the address directly.

3. Server address

https://api.onavoice.ai/v1/mcp

The server uses Streamable HTTP and is stateless: nothing is kept between requests, and every request stands alone.

• Send JSON-RPC messages with POST. A GET answers 405, and a DELETE answers 204 with nothing to end.
• Send Accept: application/json, text/event-stream and Content-Type: application/json.
• JSON-RPC batches (an array of messages in one request) are refused with a 400. Send one message per request.
• Responses are never cached.

A request without a valid token answers 401. Tokens only work at this address: an Ona token is refused anywhere else, and Ona's other endpoints refuse tokens made for this server.

4. Sign in with Ona

This is the way most people connect, and the way Claude and Cursor do it. It is OAuth 2.1 with PKCE (the S256 method is required) and public clients, so there is no client secret to store.

• Discovery. A request to the server without a token answers 401 with the header WWW-Authenticate: Bearer resource_metadata="https://api.onavoice.ai/.well-known/oauth-protected-resource/v1/mcp". That document points to the authorization server, described at https://api.onavoice.ai/.well-known/oauth-authorization-server.
• Registering an assistant. Dynamic client registration is supported (POST https://api.onavoice.ai/oauth/register), and so are client ID metadata documents.
• Approving. The assistant sends you to Ona's own screen. You choose Read only (the default) or Read and add to-dos, and approve.
• Scopes. ona:read and ona:todos:write. See Permissions.
• Tokens. Access tokens start with onat_ and last 1 hour. The assistant refreshes them without asking you again.

The approval link an assistant opens is valid for 10 minutes. You can have at most 20 assistant connections on one account.

5. API keys

If an assistant or a script cannot use Sign in with Ona, use an API key. Make one in the Ona web app under Settings, Developers. A key is shown once when you make it, you can give each key only the permissions it needs, and you can revoke it at any time. An account can have 10 keys at once.

Send the key as a bearer token. Keys start with ona_.

Authorization: Bearer ona_...

For example, this lists the tools the key can use:

curl https://api.onavoice.ai/v1/mcp \
  -H "Authorization: Bearer ona_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Keep a key as private as a password. Anyone who has it can read what its permissions allow.

6. Add it to an assistant

In the Ona web app, open Settings, Connections, External AI. There are three rows:

• Claude. Add shows the name and the address, then Open Claude opens Claude's add-connector screen. Paste them there and sign in with Ona when Claude asks.
• Cursor. Add opens Cursor with the server already filled in. Approve it in Cursor, then sign in with Ona.
• MCP. For any other assistant that supports remote MCP servers. It shows the address to use with sign-in, and the address to use with an API key.

Once connected, the connection appears in the same list, with its activity.

7. Permissions

Every connection is read only unless you allow more. A tool the connection may not use is left out of the tool list, and calling it anyway answers forbidden.

API keys carry these key scopes instead, and you choose them when you make the key:

list_templates is available to API keys only. A connection made with Sign in with Ona cannot use it.

8. Tools

The server offers eight tools. A connection sees only the ones its permissions allow. Every tool works on your own account and nothing else.

Dates are written YYYY-MM-DD and read in your account's time zone. Ids come from earlier results. Every tool rejects an argument it does not know, and answers invalid_arguments naming the field.

Results are capped at 80,000 characters. When a result is cut, it says so with "truncated": true. get_meeting shortens the summary first, then drops to-dos from the end. get_transcript and the listing tools return pages instead: pass next_cursor back as cursor to continue.

search_meetings

Finds your conversations. With a query it returns the ones that best match what was said, by meaning and by keyword. Without one it lists the newest first. Read.

• query, text, optional. What to look for, up to 500 characters.
• from, date, optional. First day, inclusive.
• to, date, optional. Last day, inclusive. It must not be before from.
• folder, text, optional. A folder id or its exact name.
• limit, whole number, optional. 1 to 20, default 10.
• cursor, text, optional. The next_cursor of the previous page. A search with a query reaches the 40 best matches.

Returns meetings, each with id, title, url (the conversation in Ona), recorded_at, a short excerpt of the summary, its folder, and, for a query, up to two matches with the passage, its time and the speaker. Returns next_cursor when there is more. Errors: invalid_arguments, not_found (no folder matches), forbidden, plan_required.

get_meeting

Returns one conversation. Read.

• id, text, required. The conversation id, from search_meetings.

Returns meeting (id, title, url, recorded_at, duration_minutes, folder, has_transcript), the summary notes as text, and action_items with id, description, status, due_on and assignee. Dismissed to-dos are left out. Errors: not_found, invalid_arguments, forbidden, plan_required.

get_transcript

Returns a conversation's transcript as lines of the form [mm:ss] Name: text, one page at a time. Read.

• meeting_id, text, required. The conversation id.
• from_seconds, number, optional. Start at the first line at or after this many seconds into the recording. 0 up to 172,800.
• cursor, text, optional. The next_cursor of the previous page.
• max_chars, whole number, optional. Page size in characters, 500 to 80,000, default 20,000.

Returns meeting_id, title, url, transcript, start_seconds and end_seconds for the page, and next_cursor when there is more. Errors: not_found, invalid_arguments, forbidden, plan_required.

list_folders

Lists your folders. Read.

• No inputs.

Returns folders, each with id, name, parent_id and description, in the order they appear in Ona, up to 500. Errors: forbidden, plan_required.

list_action_items

Lists your to-dos, the one changed longest ago first. Read.

• status, open, done or dismissed, optional. All when left out.
• updated_since, time, optional. An ISO 8601 time with a Z or an offset, such as 2026-09-30T08:00:00Z. Items changed from 60 seconds before it are returned, so remove repeats by id and updated_at.
• limit, whole number, optional. 1 to 100, default 50.
• cursor, text, optional. The next_cursor of the previous page.

Returns action_items, each with id, description, status, due_on, assignee, meeting_id, meeting_url, created_at and updated_at, and next_cursor when there is more. Errors: invalid_arguments, forbidden, plan_required.

create_action_item

Adds a to-do to your list. It needs the Read and add to-dos permission, or a key with the action_items:write scope. Write.

• description, text, required. What needs doing, 1 to 500 characters.
• due_on, date, optional. The due date.
• meeting_id, text, optional. A conversation id, to attach the to-do to it.

Returns action_item (the same fields as in list_action_items) and already_existed. Sending the same request again within two minutes returns the first item with already_existed: true instead of adding a second. Errors: invalid_arguments, not_found (no such conversation), conflict (a to-do with the same wording already exists on that conversation, or the same request is still being handled), forbidden, plan_required.

list_templates

Lists the summary templates you can use: Ona's own and the ones you made. API keys only, with the templates:read scope. Read.

• No inputs.

Returns templates, each with id, name, description and is_core (true for Ona's own). The template's prompt text is not returned. Errors: forbidden, plan_required.

get_recap

Returns your daily recap for one day, or every recap in a range of days in one call: headline, overview, highlights, decisions, open questions, action items and stats. Read.

• date, date, optional. One local day. Give this, or from and to.
• from, date, optional. The first local day of a range. Needs to.
• to, date, optional. The last local day of a range, included. A range covers at most 31 days.

For one day, returns date and recap. A day with no recap is not an error: recap is null and a note says why (nothing was recorded, there was too little to recap, or the recap has not been made yet).

For a range, returns from, to, recaps (newest day first) and days_without_recap, the days in the range that have none. If the range is too large for one result, the oldest days are left out, truncated is true and days_not_returned lists them.

Errors: invalid_arguments (no day given, date together with a range, a range missing one end, from after to, or more than 31 days), forbidden, plan_required.

9. Errors

A tool that cannot do what was asked answers with a normal result marked as an error. Its text is JSON of the form {"error": {"code": "not_found", "message": "No such meeting", "field": "id"}}. field appears when one input caused it. The message never contains your content.

Some problems are answered before any tool runs, as an HTTP status:

10. Limits

A request over a limit answers 429 with Retry-After. An assistant often sends three or four requests for one tool call, which is why a connection has a higher per-minute limit than a key.

Signing in is limited too, per address: 30 approval-page opens a minute, 600 token requests a minute and 300 client registrations an hour. Approving or denying on Ona's screen is limited to 30 a minute per account, and the sign-in requests themselves are limited to 64 KB. An address that sends many invalid tokens is slowed with 429.

11. How long a connection lasts

• An access token lasts 1 hour. The assistant refreshes it for you.
• A connection ends after 90 days without use.
• Even with regular use, a connection needs approving again after 12 months.
• An API key lasts until you revoke it.

When a connection ends, the assistant has to ask you to sign in again.

12. What Ona records

For every tool call Ona keeps one line: which tool was called, the ids of the conversations it touched (up to 50) and the outcome. It never keeps the question, the search words or any content.

These lines are kept for 90 days. You can see them for each connection in Settings, Connections.

13. Disconnecting

Open Settings, Connections in the Ona web app, choose the connection and disconnect it. It stops on its next request. To end an API key, revoke it under Settings, Developers.

Disconnecting stops new reads. It does not take back what the assistant has already read: see the next section.

14. Your data and connected assistants

What the tools return is your own recorded conversations. It can include other people's words.

Once an assistant has read something, what it does with it is governed by that assistant's own terms and privacy policy, not by Ona's. What it has already read may stay in its own history after you disconnect it. Connect an assistant only if you are comfortable with that, and only to conversations you have the right to share.

The server tells an assistant that everything the tools return is your recorded speech and notes, and is data, not instructions.

15. Security

Tokens only work at the server address above. Ona stores them as hashes, so a token cannot be read back, and a token is refused at any other Ona address.

To report a vulnerability, email info@onavoice.ai.