> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maybloc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI agent to the Maybloc API with MCP

> Let Claude Code, Codex, Cursor, VS Code or Gemini transcribe recordings and read results through the Maybloc MCP server. One command per agent, authenticated with an API key.

The Maybloc MCP server lets an AI agent upload a recording, transcribe it, and read who said what, with the same API keys, prices and limits as the REST API. It is at `https://mcp.maybloc.com/mcp`, and a request needs `Authorization: Bearer mbk_live_...`.

## How do I connect an agent?

Create an API key in the [console](https://app.maybloc.com/developers/keys), then add the server to your agent. Use a read-only key to let an agent look things up, and a full-access key to let it transcribe.

**Claude Code**

```bash theme={null}
claude mcp add --transport http maybloc-api https://mcp.maybloc.com/mcp \
  --header "Authorization: Bearer $API_KEY"
```

Your shell fills in the key when you run the command, and Claude Code stores it in its local configuration.

**Codex**

```bash theme={null}
export API_KEY=mbk_live_...
codex mcp add maybloc-api --url https://mcp.maybloc.com/mcp --bearer-token-env-var API_KEY
```

Codex stores only the name of the environment variable, never the key.

**Cursor**

Add this to `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for every project:

```json theme={null}
{
  "mcpServers": {
    "maybloc-api": {
      "url": "https://mcp.maybloc.com/mcp",
      "headers": { "Authorization": "Bearer ${env:API_KEY}" }
    }
  }
}
```

**VS Code**

Add this to `.vscode/mcp.json`. VS Code asks for the key once and keeps it out of the file:

```json theme={null}
{
  "servers": {
    "maybloc-api": {
      "type": "http",
      "url": "https://mcp.maybloc.com/mcp",
      "headers": { "Authorization": "Bearer ${input:maybloc-api-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "maybloc-api-key", "description": "Maybloc API key", "password": true }
  ]
}
```

**Gemini CLI**

```bash theme={null}
gemini mcp add --transport http --header "Authorization: Bearer $API_KEY" maybloc-api https://mcp.maybloc.com/mcp
```

Any other client that supports streamable HTTP servers and a custom header works with the same address and header. The commands above follow each agent's own MCP documentation, which is the place to look if a client changes its syntax.

## Which tools does the MCP server have?

| Tool | What it does | Key needed |
| - | - | - |
| `get_account` | The workspace's name and credit balance. | Any key |
| `estimate_cost` | The price of transcribing a recording of a given length with a given configuration, before anything is spent. | Any key |
| `list_transcripts` | The workspace's transcripts, newest first, a page at a time. | Any key |
| `get_transcript` | A transcript's status (queued, processing, completed, failed or canceled), its configuration, speaker names, length and cost. | Any key |
| `get_transcript_result` | What was said in a completed transcript: speakers, turns in time order with who said what and when, where people overlapped, conversation analytics, and the output of any add-ons. | Any key |
| `export_transcript` | A completed transcript as a file's text: srt or vtt subtitles with speaker names, or txt with a time before each turn. | Any key |
| `read_docs` | This API's documentation. | Any key |
| `create_upload` | Step 1 of sending a recording. | Full-access key |
| `complete_upload` | Step 2: after the file has been sent to the upload\_url, verify it so it can be transcribed. | Full-access key |
| `create_transcript` | Starts a transcript of a completed upload and holds its price from the balance; it is charged when the transcript completes, and a failed or canceled one is not charged. | Full-access key. Spends credit. |
| `add_addons` | Adds add-ons (or translation languages, or custom questions) to a completed transcript without transcribing again. | Full-access key. Spends credit. |
| `update_transcript` | Change the transcript's file name, or give speakers names (for example speaker\_1 is Maya). | Full-access key |
| `cancel_transcript` | Stops a queued or running transcript. | Full-access key |
| `delete_transcript` | DELETES for good: the recording and its transcript are removed now and cannot be recovered. | Full-access key |

A read-only key is offered only the tools that do not change anything. Tools that spend credit say so in their description, and `estimate_cost` returns the exact price before anything is spent.

## How does an agent transcribe a file?

The agent follows the same flow as the API: check the balance, estimate the price, create an upload, send the file, complete the upload, create the transcript, then read the result.

The file itself never passes through the MCP connection. `create_upload` returns a signed address, and the agent sends the file there with an HTTP PUT, for example with `curl`. This keeps large recordings out of the agent's context.

## How do I teach an agent the whole workflow?

Install the Maybloc skill. It gives the agent the workflow, the price, the limits and the safety rules in one file, and it works with any agent that supports skills:

```bash theme={null}
npx skills add https://app.maybloc.com
```

The command uses the open-source [skills CLI](https://github.com/vercel-labs/skills), which finds the skill from the address of this service.

## Is it safe to give an agent a key?

Treat an agent key like any production credential. Create a separate key for each agent so you can revoke it alone, and prefer a read-only key unless the agent has to transcribe. A full-access key can spend credit and delete transcripts.

Transcript text is what people said in the recording, so the server marks it as data to read and never as instructions to follow. Agents should still show you the price and get your approval before they call `create_transcript`.

## Can an agent read these docs?

Yes. The `read_docs` tool returns any page of this documentation as Markdown. The documentation also has its own search MCP server at `https://docs.maybloc.com/mcp`, and an index of every page at `https://docs.maybloc.com/llms.txt`. See [use the docs with AI agents](https://docs.maybloc.com/guides/ai-agents.md).


## Related topics

- [Use the Maybloc docs with AI agents and coding assistants](https://docs.maybloc.com/guides/ai-agents.md)
- [Languages supported by the Maybloc API](https://docs.maybloc.com/guides/languages.md)
- [Maybloc API errors, rate limits and idempotency](https://docs.maybloc.com/guides/errors-and-limits.md)
- [Maybloc API pricing: per-minute rates and add-on prices](https://docs.maybloc.com/guides/pricing.md)
- [Export a Maybloc transcript as SRT, WebVTT or text](https://docs.maybloc.com/guides/subtitles-and-exports.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.