Monologue MCP server
Commit Oct 25, 2026Creates a unified timeline of actions taken by AI agents, such as sent emails, submitted forms, and pushed code, for easy review and monitoring.
Also known as willcheung/monologue
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Oct 25, 2026
- License
- MIT
What is Monologue MCP?
Monologue creates a unified timeline of actions taken by AI agents, such as sent emails, submitted forms, and pushed code, for easy review and monitoring.
Summary generated from the project's README
About Monologue MCP server
Monitoring the tangible impact of autonomous agents is what Monologue enables for developers and teams. It creates a unified timeline of agent actions, such as sent emails, submitted forms, or pushed code, while filtering out internal reasoning and research to maintain a high signal-to-noise ratio. This allows users to track exactly what an agent changed across various products in one central feed.
Users can run Monologue locally in single-user mode using a SQLite database or deploy it in cloud mode with Google sign-in and Turso persistence. The system supports both REST API reporting via a private key and an OAuth-based MCP endpoint for reading timelines. Developers integrate it by adding the Monologue skill directory to their agent or using the provided Python reporting script. It is designed to be portable, working with both native skill discovery and agents that load instructions directly.
What you can do with it
- 1Audit agent activityReview a single timeline of all external changes made by your AI agents across different platforms.
- 2Monitor code deploymentsTrack when an agent successfully pushes code to a remote repository.
- 3Track financial transactionsKeep a record of purchases or transactions executed by an autonomous agent.
Written from the project's README. Every use case is checked against a quote from it.
How to install Monologue MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Monologue MCP in Claude Code
$ claude mcp add --transport http monologue https://www.monologue.events/mcpInstall Monologue MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"monologue": {
"url": "https://www.monologue.events/mcp"
}
}
}Install Monologue MCP in VS Code
.vscode/mcp.json
{
"servers": {
"monologue": {
"type": "http",
"url": "https://www.monologue.events/mcp"
}
}
}Install Monologue MCP in VS Code CLI
$ code --add-mcp '{"name":"monologue","type":"http","url":"https://www.monologue.events/mcp"}'Install Monologue MCP in Codex
$ codex mcp add monologue --url https://www.monologue.events/mcpInstall Monologue MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.monologue] url = "https://www.monologue.events/mcp"
Install Monologue MCP in Gemini CLI
$ gemini mcp add -s user --transport http monologue https://www.monologue.events/mcpInstall Monologue MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"monologue": {
"url": "https://www.monologue.events/mcp",
"type": "http"
}
}
}Configuration
BETTER_AUTH_SECRETBETTER_AUTH_URLDATABASE_URLGOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETMONOLOGUE_API_KEYMONOLOGUE_MODEMONOLOGUE_URLTURSO_AUTH_TOKENTURSO_DATABASE_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewillcheung/monologue is public and reachablegithub.com/willcheung/monologue ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/willcheung/monologue ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubMonologue
Your agent feed.
Monologue is an open-source feed of what your AI agents did for you.
It records things agents change — emails sent, forms submitted, purchases made, code pushed, calendar events changed, transactions executed — while ignoring research, reasoning, browsing, and other internal work.
Why
As people use more autonomous agents, their actions become scattered across different products. Monologue creates one timeline of what they changed.
Core rule
If your agent changed something, it shows up in Monologue.
A message sent belongs in the feed. Reading fifty messages does not. Code pushed to a remote repository belongs; local edits, commits and tests do not. The feed stays useful by staying strict about signal.
Quick start
Requirements: Node.js 22.12+ and npm (CI uses Node.js 22).
git clone <your-monologue-repository-url>
cd monologue
npm install
cp .env.example .env
Set a private key in .env:
DATABASE_URL="file:./monologue.db"
MONOLOGUE_MODE="single-user"
MONOLOGUE_API_KEY="replace-this-with-a-long-random-value"
MONOLOGUE_URL="http://localhost:3000"
Create and seed the local SQLite database, then start Monologue:
npm run db:migrate
npm run db:seed
npm run dev
Open http://localhost:3000 for the website or http://localhost:3000/feed for the feed. The SQLite file lives at prisma/monologue.db and is ignored by git.
Send a test action
With the development server running and MONOLOGUE_API_KEY exported in your shell:
curl -X POST http://localhost:3000/api/actions \
-H "Authorization: Bearer $MONOLOGUE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentName": "Codex",
"verb": "pushed",
"summary": "Pushed the first Monologue feed implementation.",
"category": "code",
"status": "completed",
"system": "GitHub",
"objectType": "commit",
"objectName": "abc123",
"project": "Monologue",
"externalId": "abc123",
"source": "self_reported"
}'
The response is {"success":true,"id":"..."} and the action appears at the top of the feed. Sending it again returns the same ID with "duplicate":true.
Connect an agent
Copy the whole skills/monologue directory into your agent's supported skills directory. Configure the agent's persistent environment or secure secret store with your self-hosted instance and its ingestion key:
MONOLOGUE_URL="http://localhost:3000"
MONOLOGUE_API_KEY="the-key-configured-on-your-instance"
Keep the URL and key together and use your agent's secure configuration mechanism. For a remote agent, use the reachable HTTPS URL of your own deployment. No Monologue hosted account or marketplace plugin is required for single-user mode.
The same portable skill supports clients with native skill discovery and agents that load instructions directly. Copying only skills/monologue/SKILL.md works when the agent will POST directly rather than use the helper.
After any installation method, confirm monologue appears in the agent's available-skills list. Reload skills or start a new session when the agent builds that list at session start. Installation is not complete until the skill is discoverable.
The included helper has no dependencies:
python3 skills/monologue/scripts/report-action.py \
--agent Codex \
--verb pushed \
--summary "Pushed the first Monologue feed implementation." \
--category code \
--system GitHub \
--project Monologue \
--external-id abc123
Reporting is required, with best-effort delivery. Capture the returned event ID; a clean helper exit can also mean delivery was skipped. Note any reporting gap without breaking the primary task.
Hosted mode and Google sign-in
The standalone application includes both single-user mode and an optional multi-user cloud mode for your own deployment. Single-user mode uses local SQLite and MONOLOGUE_API_KEY. Cloud mode adds Google sign-in, personal workspaces, revocable agent keys, and SQLite-compatible Turso persistence. Plugin packaging and marketplace distribution are private and are not included in this public checkout.
Set these variables for cloud mode:
MONOLOGUE_MODE="cloud"
BETTER_AUTH_SECRET="replace-with-at-least-32-random-characters"
BETTER_AUTH_URL="https://monologue.example.com"
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
TURSO_DATABASE_URL="libsql://..."
TURSO_AUTH_TOKEN="..."
Create a Google OAuth web client and register this exact callback URL:
https://monologue.example.com/api/auth/callback/google
Google sign-in requests only openid, email, and profile. It does not grant Monologue access to Gmail, Calendar, Drive, or other Google services. New users are taken to /settings/keys, where they can copy the setup prompt to add an agent. Someone signing up through an agent connection link returns to that link to approve automatic key creation. Returning users go to /feed or their requested page.
For a Vercel deployment backed by Turso:
vercel link
vercel integration add tursocloud/database
vercel env pull .env.local
npm run db:migrate:turso
Choose a Turso region close to the Vercel Function region. Add the remaining cloud-mode variables in Vercel, then deploy with vercel --prod. Apply committed Turso migrations before deploying code that depends on them; the migration runner records checksums and safely skips migrations already applied.
See docs/HOSTED_ARCHITECTURE.md for application structure, tenant isolation rules, and deployment checks.
Optional browser and server error monitoring uses Sentry. See docs/SENTRY.md for isolated project setup, deployment variables, collection boundaries and verification. Monitoring stays off without a DSN and during local development.
API
The hosted OAuth MCP endpoint is /mcp; it does not accept REST API keys. Its two tools use the same action data and workspace permissions. read_timeline defaults to 25 results (maximum 100), supports filters and cursor pagination, and excludes raw metadata and credential identifiers. OAuth tokens cannot authenticate to REST. See MCP setup and rollout for scopes, configuration and migration requirements.
REST reporting works in single-user mode with the configured key. OAuth MCP requires your own cloud-mode deployment with browser sign-in; connect a compatible client to https://<your-deployment>/mcp and approve reading and reporting together for the workspace you choose. Both follow your current membership; older limited grants remain limited until you reconnect.
Both routes require Authorization: Bearer <MONOLOGUE_API_KEY>.
POST /api/actionsvalidates and creates an action. Required fields:agentName,verb,summary,category,status, andsystem.GET /api/actionsreturns newest first and acceptsagent,category,status,system,project,from,to, andsearchquery parameters.
Hosted automatic connection uses three short-lived endpoints:
POST /api/connect/requeststarts a ten-minute connection request for an agent. It requiresagentNameand optionally acceptsplatformandskillVersion.POST /api/connect/approverequires a signed-in browser session and approves that request for the user's workspace.POST /api/connect/polllets the requesting agent claim its generated key exactly once after approval.
Only hashes of the device and approval codes are stored. The long-lived API key is created at claim time, returned once to the agent, and then stored by Monologue only as a hash. Automatic keys are scoped to actions:write; existing and manually created keys retain read and write access for compatibility.
Monologue derives stable agent identity from the authenticated connection instead of trusting a submitted agentId. Older keys are attached to an Agent automatically on their next write, so installed skills remain compatible. Agent-key ingestion is always stored as self_reported; verified and observed are reserved for future trusted ingestion paths.
externalId is optional. When supplied, the tuple (agentName, system, externalId) is unique and retry-safe. No fuzzy deduplication is performed.
Use url for the action's primary destination—the commit, order, event, payment, or other changed object. Use the free-form metadata JSON object for provider-specific details and secondary links:
{
"url": "https://amazon.com/orders/7741",
"metadata": {
"orderNumber": "113-4820917-7741",
"quantity": 2,
"receiptUrl": "https://amazon.com/orders/7741/invoice"
}
}
The detail drawer presents the primary URL as an “Open in…” button and formats metadata as readable rows.
Supported categories: communication, calendar, purchase, reservation, finance, code, file, task, account, crm, database, deployment, form, other.
Supported statuses: completed, failed, pending. Supported sources: self_reported, verified, observed.
Architecture
AI agent → Monologue skill → POST /api/actions → validation + dedupe → SQLite
├─ Feed
├─ AI Crew profiles
├─ Weekly agent ledger
├─ Filters + search
├─ Action details
└─ Browser-generated static share cards
Next.js renders the product directly from one SQLite-compatible database through Prisma. Local mode uses one SQLite file; hosted mode uses workspace-scoped libSQL/Turso. Recap combines a 28-day activity matrix and current streak, the seven-day ledger and a last-24-hours report. The activity matrix and weekly ledger aggregate recorded completed actions at the same capture time. Share cards are rendered as static PNGs in the browser and are never uploaded or connected to future activity. The API and product pages use the same validation and data-access layer, with no queue, cache, analytics service, or charting framework.
Deployment architecture and the Google sign-in boundary are documented in docs/HOSTED_ARCHITECTURE.md. Both runtime modes share the same application, API, persistence layer, and portable skill.
Development checks
npm run lint
npm run typecheck
npm test
npm run test:libsql
npm run test:reporter
npm run test:browser
npm run build
Pull requests and pushes to main run these checks in GitHub Actions, alongside the existing public-repository privacy check. CI uses Node.js 22, Python 3.12, and disposable local databases; it needs no hosted credentials and does not deploy. typecheck generates Next.js route types before checking TypeScript so it works in a fresh checkout (generate the Prisma client first with npx prisma generate).
test:libsql reruns the MCP, workspace, and REST/connection route integration tests using the libSQL adapter. test:reporter uses Python's standard library to test the portable reporter without network calls or Keychain access. The route tests exercise real validation, credentials, and persistence; only browser session resolution is mocked. Real Google sign-in is outside these tests.
For the browser suite, install Chromium once with npx playwright install chromium (npx playwright install --with-deps chromium on Linux). test:browser starts its own loopback server and disposable database with synthetic accounts. It checks Recap navigation, focus, responsive charts, static sharing and real PNG exports. It never uses production credentials or data. Native share sheets are simulated; physical-device behavior needs separate verification.
To enforce the checks before merging, make Quality checks and the existing privacy job required in your GitHub branch rules for main.
To recreate the database from scratch and reseed it:
npm run db:reset
V2 extension points
The Action API and source field can later accept webhooks, connectors, MCP, browser agents, or native integrations without changing what the consumer sees. A database migration can move the schema to Postgres when needed. Those transports—and accounts, teams, OAuth, policies, analytics, agent metrics, and automatic grouping—are intentionally outside V1.
License
MIT
Shared-workspace development preview
Run npm run dev:workspace, then open http://localhost:3100/feed. This starts the same application with an isolated SQLite database and synthetic sample accounts. Use the sample-account selector to try personal/shared feeds, invitations, member removal, assistant destinations, and daily report settings. Team settings include a development-only Free/Plus switch.
The launcher suppresses hosted database/provider credentials and binds to loopback. No production data is loaded, no email or Slack messages are sent, and no daily delivery job or checkout is connected. Stop with Ctrl+C. Development account switching is unavailable in production. See workspace architecture for authorization and migration details.
Monologue MCP questions
How do I add Monologue MCP to Claude Code?
Run claude mcp add --transport http monologue https://www.monologue.events/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Monologue MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does Monologue record?
It records tangible changes made by agents, such as emails sent, forms submitted, purchases made, code pushed, and calendar events changed.
What is the difference between single-user and cloud mode?
Single-user mode uses a local SQLite database and an API key, while cloud mode adds Google sign-in, personal workspaces, and Turso persistence.