START HERE
Connect an AI agent to a browser through MCP
Use your deployment's /mcp endpoint and a separate agent credential. MCP is the protocol your agent uses to call browser tools; the dashboard password is for your own sign-in.
The two connection details
https://YOUR_HOST/mcp
Authorization: Bearer YOUR_AGENT_TOKENReplace YOUR_HOST with the host of your own Tallylamp deployment. The public tallylamp.dev website is a guide and product demo; it is not your browser service. For local development, the endpoint is http://127.0.0.1:8080/mcp.
Your client must support remote MCP over Streamable HTTP and one of the authentication methods below. Its support for MCP alone does not prove that its authentication flow works with this server.
From 0.11.3, agents sharing one MCP connection should pass their own browserId on every browser call, including recording start/stop. Explicit IDs let different browsers run independently without changing the shared default. tallylamp_create_browser and tallylamp_use_browser still change that default, so calls without an ID can follow another agent's selection. Keep passing the ID after reconnecting; if the credentials have been used for multiple browsers, select the target explicitly.
For clients that accept a bearer token
Create an agent
Open Agents in the dashboard. Create a named agent, tick the permissions it needs, and copy its token.
Configure the client
Add the endpoint as an HTTP MCP server. Put the agent token in its bearer-token setting or Authorization header. Use the client's secret or environment-variable support where available.
Check the connection
Reconnect the MCP client and ask it to list Tallylamp browsers. If it can list them, ask it to create one and open https://example.com. Confirm the new browser in your dashboard.
For clients that use OAuth
Sign into the Tallylamp dashboard first. Add your /mcp URL in the client, then approve the connection on Tallylamp's consent page. Check the client name and the host receiving the authorization code before approving.
Approval creates a connector agent with ordinary agent permissions and a browser cap. You can disconnect it from the Agents page. Tallylamp supports public OAuth clients; a client that requires a confidential client secret needs a different authentication setup.
If the first call fails
| What you see | What to check |
|---|---|
| The dashboard page instead of tools | Use /mcp, not the deployment's root URL. |
| An authentication error | Check that the agent is enabled and the current token reaches every request. |
| Only authentication tools | Complete the OAuth flow, then reconnect or refresh the client's tool list. |
| A tool says a human has control | Choose Return to agent in the live viewer, then ask the agent to retry. |
| Browser creation is refused | Check the agent's permissions, its browser cap, and the deployment's available slots. |
The compatibility reference includes configuration examples for Claude Code, Codex CLI, Cursor, and VS Code, along with the evidence for each. The repository tests the MCP protocol; those tests do not certify every external client.
Docs behind this guide
Based on Tallylamp's documented behaviour. See the source for API details and release-specific settings.