Work with a coding agent
Your coding agent (Claude Code, or any MCP client) can do every step of a Voqalize integration from your editor: create the agent, mint its keys, run the brain, and read back what a session did. It does this through the hosted Voqalize MCP server, and it learns the product from these docs.
Connect the MCP server
Section titled “Connect the MCP server”The server is hosted at https://app.voqalize.com/mcp/. There is nothing to
install. In Claude Code:
claude mcp add --transport http voqalize https://app.voqalize.com/mcp/Or, for everyone working in a repository, add .mcp.json at its root:
{ "mcpServers": { "voqalize": { "type": "http", "url": "https://app.voqalize.com/mcp/" } }}Any other MCP client takes the same two things: a name and that URL over HTTP. On first use the client opens a browser for a Google sign-in, the same login as the console. There is no API key or client secret to configure.
What your agent reads
Section titled “What your agent reads”- The handshake. On connect, the server gives your agent one paragraph that explains brain, agent and session, and links to the docs.
- The docs as markdown. Every page on this site is also served as raw
markdown at its URL plus
.md(for examplehttps://docs.voqalize.com/build/quickstart.md), and/llms.txtindexes them, one line each. - The tools. Each tool describes itself, and a refused call comes back with a message saying why. MCP server lists every tool and its arguments.
Every tool but whoami, list_tenants and create_tenant takes a tenant
slug. Calls are limited to 120 a minute per tenant.
The flow, end to end
Section titled “The flow, end to end”This is the order an agent with these tools takes a project from empty to a running voice agent:
- Find the tenant.
whoami, thenlist_tenants. Choose the tenant by itsnameand pass itsslugastenantto every other tool. An empty list means there is no tenant yet: callcreate_tenant. - Write the brain. A
Brainsubclass withgreetandon_user_message, then the callbacks it needs. See Build the brain. - Test it unattended. The conformance harness drives the brain over the real wire, with no audio, no model and no person.
- Create the agent.
create_agent(tenant, name)returns the agent (with itstest_url) and asession_key: ansk_key, shown once, for your server. - Say how Voqalize reaches the brain. Locally,
create_agent_credentials(tenant, agent_id)puts the agent on the Cortex relay and returnsagent_secretandcortex_urlforserve(...); no tunnel. In production,update_agent(tenant, agent_id, brain_url="wss://…")points it at an inbound route. Until one of these is done, every session is refused withagent_not_configured. See Deploy the brain. - Talk to it. Run the brain and open the agent’s
test_url, the console Playground. - Put it in the app. A server route that calls
sessions.connectwith thesk_key, and your client on@voqalize/client-transportin the page. For a public page with no login, mint a browser key withcreate_api_key(tenant, agent_id, label, kind="publishable", allowed_origins=[…]). See Connect your app. - Read sessions back.
list_sessions, thenget_call_recordfor what was said and heard, andget_session_logsfor Voqalize’s side. See Reading a call back.
A prompt that works
Section titled “A prompt that works”Name the outcome, where it goes in your app, and how you will check it:
Add a Voqalize voice agent to this app. Read https://docs.voqalize.com/llms.txtfirst. Put the brain in backend/voice/brain.py using OpenAIBrain, with a toolthat reads the current order. Run it locally over Cortex, give me the test_url,and once I confirm it answers, add a "Talk to us" button to the order page thatstarts a session through a new /api/voice/start route.Ask for the harness tests in the same request if you want them written before the agent goes live.
Stage skills
Section titled “Stage skills”If your app uses Stage, the public repository ships five Claude
Code skills for it in
.claude/skills/:
| Skill | Use it to |
|---|---|
stage-author | Add Stage to your web app: the spec, the page’s performers and the state events. |
stage-move | Add or change one move in your Stage Spec, then regenerate and check it. |
stage-debug | Turn a session into a timeline of speech against screen, to find why the page did not move. |
stage-review | Review a diff that touches Stage against Stage’s rules. |
stage-explorer | Study a live website you do not control and write its Stage Spec. |
Copy them into your project, where Claude Code loads project skills from. They cite the Stage contract and example in the public repository, so keep a clone beside your project:
git clone --depth 1 https://github.com/voqalize/voqalize ../voqalizemkdir -p .claude/skillscp -r ../voqalize/.claude/skills/stage-* .claude/skills/Read next
Section titled “Read next”- Quickstart: the same flow, by hand.
- MCP server: every tool, argument and return value.
- Reading a call back: debugging a session from your editor.