> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vowen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP server
> Expose your dictation history, notes, and transcripts to Claude Code and other MCP clients.
`vowen mcp` runs a Model Context Protocol server over stdio. Point any MCP client at it and that client can search your dictations, read your meeting notes, transcribe audio files, and manage your dictionary, all through the running Vowen app.
```bash theme={null}
claude mcp add vowen -- vowen mcp
```
That is the whole setup for [Claude Code](https://claude.com/claude-code). Restart your session and ask it something like "what did I dictate about the migration last week?"
**This is the outbound direction: agents reading Vowen.**
Vowen also has an inbound MCP feature, [Connectors](/integrations/connectors), where Vowen's own AI reaches out into your other apps. The two run in opposite directions:
* **`vowen mcp` (this page):** Vowen *is the server*. An external agent connects to it and reads your Vowen data. Runs through the CLI, no plan gate beyond what the underlying operations already require.
* **[Connectors](/integrations/connectors):** Vowen *is the client*. It connects out to Linear, Notion, GitHub and others so its AI can look things up while answering you. Configured in the app, Pro and experimental.
## Requirements
* The [`vowen` CLI installed](/cli/installation) and on your PATH.
* The Vowen desktop app installed. The MCP server launches it in the background on the first tool call if it is not already running.
The server holds one connection to the app for the whole session and re-establishes it automatically if the app restarts, so a Vowen update mid-conversation does not break your agent.
## Setting up a client
```bash theme={null}
claude mcp add vowen -- vowen mcp
```
Verify with `claude mcp list`, then start a session and ask it to search your history.
Any client that speaks MCP over stdio works. Register a local server with:
* **command:** `vowen`
* **arguments:** `["mcp"]`
That is all the process needs. There are no environment variables to set and no port to configure, because the CLI discovers the running app itself.
If your client wants an absolute path rather than a bare command, `vowen doctor` prints the path the binary was installed to.
Do not run `vowen mcp` in your terminal to "check that it works". It reads JSON-RPC from stdin and will simply sit there. Use `vowen doctor` to verify the connection and let the client own the process.
## Available tools
23 tools, grouped by what they touch.
### Reading your data
| Tool | What it does | Key parameters |
| ----------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `search` | Full-text search across dictations, file transcriptions, and meeting notes. Returns compact matches | `query` (required), `limit`, `type` |
| `history` | List recent items, newest first | `limit`, `type`, `since`, `before` |
| `read_item` | Full text and metadata of one item. Omit the id for the latest dictation | `id` |
| `stats` | Lifetime dictation statistics, last-30-days activity, and per-type counts | none |
`type` is one of `dictation`, `transcription`, `note`, or `all`. `search` defaults to `all`, `history` defaults to `dictation`. Dates are `YYYY-MM-DD`. Item ids may be given as a prefix.
Search first, then `read_item` on whatever looked relevant. `search` deliberately returns snippets rather than whole transcripts.
### Meeting notes
| Tool | What it does | Key parameters |
| ------------- | ------------------------------------------------------ | ----------------------------------------------------------- |
| `note_create` | Create a meeting note from text, Markdown accepted | `text` (required), `title`, `contextNotes` |
| `note_update` | Update a note's title, text, context notes, or summary | `id` (required), `title`, `text`, `contextNotes`, `summary` |
### Transcription
| Tool | What it does | Key parameters |
| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `transcribe_file` | Queue an audio or video file for transcription. Returns a job id | `path` (required, absolute), `modelId`, `language`, `diarize` |
| `transcription_status` | Job status: `processing`, `done`, or `error`, plus the transcript once done | `id` (required) |
Transcription is asynchronous. `transcribe_file` returns immediately, so poll `transcription_status` until it reports `done`. Anything you leave out falls back to the user's configured model and language.
### Tags
| Tool | What it does | Key parameters |
| ----------- | --------------------------------------------- | ------------------------------------ |
| `tags_list` | List tags. Omit the pool to get both | `pool` (`notes` or `transcriptions`) |
| `tag_item` | Add or remove tags on a note or transcription | `id` (required), `add`, `remove` |
`tag_item` takes tag **ids**, not names. Call `tags_list` first to resolve them.
### Dictionary and text rules
| Tool | What it does | Key parameters |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `vocab_list` | List custom vocabulary terms | none |
| `vocab_add` | Add a vocabulary term. The term keeps the case you give it, and adding one that already exists is a no-op | `word` (required) |
| `vocab_remove` | Remove a vocabulary term, matching the whole term and ignoring case | `word` (required) |
| `replacements_list` | List text replacements applied to transcripts | none |
| `replacements_set` | Create or update a replacement, keyed by trigger | `trigger`, `replacement` (both required) |
| `replacements_remove` | Remove a replacement by trigger | `trigger` (required) |
| `expansions_list` | List live typing expansions | none |
| `expansions_set` | Create or update an expansion, keyed by shortcut | `shortcut`, `body` (both required) |
### Settings and app control
| Tool | What it does | Key parameters |
| -------------- | ------------------------------------------------------------- | ------------------------------ |
| `settings_get` | Read settings, secrets redacted. Optionally one top-level key | `key` |
| `settings_set` | Set a whitelisted setting | `key`, `value` (both required) |
| `record_start` | Start dictation recording in the app | none |
| `record_stop` | Stop recording, which transcribes what was captured | none |
| `app_status` | App version, plan, active model, recording state | none |
`settings_set` writes only the same whitelisted keys the CLI allows. Shortcuts, API keys, sync, and account settings cannot be changed by an agent. The full list is on the [command reference](/cli/commands#settings).
## What an agent can and cannot reach
* **It reads and writes real data.** These tools are not a sandbox. `note_update`, `vocab_add`, `replacements_set` and `settings_set` change what is in your app.
* **It cannot delete anything.** No delete tool is exposed. `vowen delete` exists on the CLI, but there is no MCP equivalent.
* **Secrets never leave.** `settings_get` redacts every key that looks like an API key, token, secret, password, or licence.
* **Everything goes through the app.** The server has no direct access to your files or stores. It makes the same loopback API calls the CLI does, so plan limits and validation apply identically.
* **Nothing is exposed off-machine.** The transport is stdio between your client and the `vowen` process, and the app's API binds `127.0.0.1` only.
## Troubleshooting
Confirm the binary is reachable under the same PATH your client sees:
```bash theme={null}
which vowen # macOS
where vowen # Windows
vowen doctor
```
GUI-launched clients frequently do not inherit the PATH from your shell profile. If `vowen` works in your terminal but not from the client, register it by absolute path instead. `vowen doctor` prints the location.
Every tool call goes through the desktop app, so it has to be reachable. Run `vowen doctor`. If it reports "App: not reachable", start Vowen and try again. See [the CLI troubleshooting section](/cli/installation#troubleshooting) for the rest.
A few operations are plan-gated. Exceeding the free lifetime transcription limit, or queuing a second transcription while one is already running, both surface as an error in the tool result. Check `app_status` for the current plan.
`vowen update` handles this. On Windows the running executable is renamed out of the way rather than overwritten, so an active `vowen mcp` process does not block the update. The client will pick up the new binary the next time it spawns the server.
## Related
How the CLI talks to the app
The other direction: Vowen's AI reading your other apps