Skip to main content
Glama
Mixedlane MCP Server

Mixedlane MCP Server

by wesolves

Mixedlane

A simpler, friendlier Jira-style tracker.

Project → Epic → Milestone → User Story → Task → Subtask, with a Kanban board, a tree list, rich-text descriptions and comments, and an activity history.

It also has:

  • Confluence-style docs.

  • Realtime collaboration (live updates, presence, an inbox).

  • GitHub automation.

  • AI agents that connect over MCP with their own API keys and permissions.

Stack

Part

Tech

Web (apps/web)

React 19, Vite, Tailwind v4, shadcn/ui (Radix), lucide-react, react-icons, TanStack Query, React Router, dnd-kit, Tiptap

Server (apps/server)

NestJS (Express), Drizzle ORM, Postgres — embedded PGlite in dev, real Postgres in prod; DB-backed job queue

Shared (packages/shared)

Zod schemas, types and hierarchy rules used by both sides

This is one npm package with a single node_modules. The project drive is FAT32, which can't create the symlinks npm workspaces need. @mixedlane/shared is resolved through path aliases (tsconfig paths, Vite resolve.alias, and SWC for the server).

How the server runs TypeScript:

  • In development: directly through SWC (@swc-node/register), which emits the decorator metadata NestJS needs.

  • For production: npm run build compiles it the same way into plain JavaScript in build/.

Related MCP server: keymaster-mcp

Run it

npm install
npm run dev          # API on :3001, web on http://localhost:5173 (demo data is seeded into an empty database)
npm run seed:reset   # wipe and reseed the demo org (dev server must be running)

On your network (LAN): npm run dev:lan exposes the web app on every interface; the API always listens on all interfaces (HOST, default 0.0.0.0) and prints its LAN addresses at startup.

  • Other devices open http://<your-ip>:5173 (use WEB_PORT=5180 npm run dev:lan if 5173 is taken — the dev server fails rather than silently switching ports).

  • MCP clients on other machines use http://<your-ip>:3001/api/mcp (or the web port + /api/mcp) with an agent key.

  • Windows: the network must be Private and Node.js allowed through the firewall (Windows asks the first time). In development any browser origin is accepted; in production list extra origins in CORS_ORIGINS.

Other scripts:

  • npm run typecheck

  • npm run test:api: Vitest against in-memory Postgres. Set TEST_DATABASE_URL=postgres://… to run the same suite against a real Postgres; its public schema is wiped.

  • npm run build: web app, then the compiled API.

  • npm start: run the build.

  • npm run db:generate: a new migration after editing apps/server/src/core/database/schema.ts.

Database

  • Dev: embedded PGlite (real Postgres compiled to WASM) at ~/.mixedlane/pgdata. Override with PGLITE_DIR.

    • It lives in your home folder because PGlite can't store data on FAT32/exFAT drives.

    • PGlite is single-process, so only the dev server may open it. A lock file prevents accidents; use npm run seed:reset (an HTTP call) rather than scripts.

  • Prod: set DATABASE_URL to a Postgres connection string.

  • Migrations live in apps/server/drizzle and are applied automatically on start.

Background jobs run on the same database (jobs table): retries with exponential backoff, dedupe keys, and recurring schedules. GitHub polling, webhook processing and emails all run as jobs.

API docs (Swagger): http://localhost:3001/api/docs. Sign in with POST /api/auth/login, click Authorize, paste the accessToken, and set the X-Org header (e.g. demo).

Demo accounts (dev): all use the password Mixedlane123.

Email

Org role

Notes

alice@mixedlane.dev

Owner

bob@mixedlane.dev

Admin

priya@mixedlane.dev

Member

Mobile team lead

sam@mixedlane.dev

Member

Mobile team

guest@mixedlane.dev

Guest

Viewer on WEB only

The demo also has an AI agent, Triage Bot, with access to APP. Its API key is written to apps/server/data/demo-agent.key on each seed, so you can connect an MCP client right away (see AI agents & MCP).

Accounts, organizations & permissions

  • Sign-in

    • Tokens: email and password. A short-lived JWT access token (15 min) is kept in memory only, and a rotating refresh token sits in an httpOnly cookie scoped to /api/auth.

    • Reuse detection: reusing an already-rotated refresh token revokes the whole session family.

    • Instant logout: signing out ends the session immediately.

    • Email flows: with MAIL_HOST configured, new accounts confirm their email through an emailed link. Without MAIL_HOST (including an empty value), new accounts are automatically marked verified and no verification email is queued, so the inbox reminder is hidden. Other emails, such as password resets and invitations, are printed to the server console when email delivery is unset. Changing email configuration does not change the verification status of existing accounts.

    • SMTP configuration: set MAIL_HOST, MAIL_PORT (default 465), MAIL_SSL (true/false, default false), and MAIL_FROM. MAIL_SSL=true means TLS immediately on connection, normally used with port 465; port 587 normally uses MAIL_SSL=false and upgrades with STARTTLS when available. MAIL_USERNAME is the provider's SMTP login (for example, support@wesolves.in), and MAIL_PASSWORD is its SMTP password or app password. Supply both credentials, or omit both for a relay that permits unauthenticated sending. Passwords are passed directly, without URL encoding. MAIL_FROM is the visible sender, for example Mixedlane <support@wesolves.in>, and must be permitted by your provider. These settings replace the previous SMTP_URL environment variable.

  • Organizations → teams → people. Anyone can create an organization, and org roles control what you can do:

    • Owner: everything.

    • Admin: manage members, teams, integrations and every project.

    • Member: sees org-visible projects and can create projects.

    • Guest: only projects they're added to.

    Invite by email or a shareable link. The invite can pre-assign teams, and accepting creates the account.

  • Project access.

    • Each project is either Organization (visible to members at a default role) or Private.

    • You can grant roles (Admin, Editor, Commenter, Viewer) to people or whole teams. An individual role overrides inherited team/default roles; without one, the highest inherited role applies. Explicit revocations block access. Viewers can comment on findings but cannot edit tickets. Org owners and admins retain admin access.

    • The UI hides what you can't do, and the server enforces it on every endpoint.

    • Projects you can't see return 404, and every query is scoped to your organization.

  • Uploads:

    • Files are served only to members of the organization that owns them.

    • A signed httpOnly cookie makes this work for <img> and <video> tags, which can't send auth headers.

Pages

All app pages live under your organization, e.g. /demo/....

URL

Page

/login, /register, /forgot-password, /invite/:token

Auth pages

/demo/projects

All projects

/demo/projects/new

Create a project

/demo/projects/APP

Overview (/board, /list and /settings tabs)

/demo/projects/APP/settings/access

Who can see and edit the project

/demo/projects/APP/story/APP-0012

A work item (URL contains its type)

/demo/settings/general, /members, /teams, /integrations

Organization settings

/demo/docs

Docs: spaces and full-text search

/demo/docs/ENG

A space: page tree and recent pages

/demo/docs/ENG/<pageId>

A page (view, edit, history)

If the type in an item URL is wrong, it redirects to the correct one.

Per-project configuration

  • Project code: 2–5 characters, starting with a letter. It can't be changed later.

  • Item number length: 4, 5 or 6 digits, set when the project is created. Keys look like APP-0001, WEB-00001 or AB-000001.

  • Work item types: turn on only the levels you need.

    • Presets: Full hierarchy, Agile, Milestones, Simple tasks.

    • An item can sit under any enabled type above it.

    • The top enabled type (and Tasks) can sit directly under the project.

    • Types that have items can't be switched off.

  • Workflow: an ordered list of statuses. Each has a name, a color and a group (To-do, In progress or Done).

    • The statuses become the board columns.

    • "Done" statuses count toward progress.

    • Renaming a status keeps its items in place.

    • Deleting one moves its items to another status in the same group.

  • Appearance: any color (color picker or hex code), and any Lucide icon (searchable) or any emoji.

Editor (descriptions & comments)

  • Markdown shortcuts as you type:

    • #, ## and ### for headings

    • **bold**, *italic*, ~~strike~~ and `code`

    • - and 1. for lists, [ ] for checklists

    • > for quotes, ```ts for code blocks

    • --- for a divider

  • Pasting Markdown text renders it, including GFM tables and fenced code with syntax highlighting.

  • Markdown source view: the Markdown toggle in the toolbar lets you edit the raw source.

  • Images and videos: upload with the toolbar buttons, paste from the clipboard (screenshots included) or drag and drop. A progress indicator shows while uploading. Click an image to zoom.

    • Allowed images: PNG, JPG, GIF, WebP and AVIF, up to 20 MB. SVG is blocked because it can contain scripts.

    • Allowed videos: MP4, WebM, OGG and MOV, up to 200 MB.

    • Files are stored in apps/server/data/uploads (override with UPLOAD_DIR) under random names, and served with range support so videos can seek.

  • @mentions: type @ to pick an org member. They get a notification if they can read the item or page.

  • Content is stored as HTML and always rendered through the editor's schema, so unsafe markup is dropped.

Realtime & notifications

  • Live updates: the browser keeps one socket.io connection (/api/socket) per org.

    • Changes by teammates, GitHub automations and (soon) AI agents refresh boards, lists, items, comments and docs instantly.

    • Other people's changes also show a short toast, e.g. "Bob Admin moved APP-0006".

  • Rooms and permissions:

    • On connect, the server checks the access token, the session and org membership.

    • Each socket joins only the rooms for projects and spaces it can read, so hidden projects never leak.

    • Rooms are re-synced when access changes and every 30 seconds. Revoked sessions are disconnected.

    • Events carry only ids and summaries. Clients refetch details through the permission-checked REST API.

  • Presence: avatars on items and pages show who else is viewing, and who is editing.

  • Inbox (sidebar): you're notified when:

    • someone assigns you an item

    • you're @mentioned in a description, comment or page

    • someone comments on your item

    • someone else moves your item

    • You never get notified about your own actions, or about things you can't read.

  • Assignees are org members, picked from a searchable list.

AI agents & MCP

Agents are first-class members of an organization, with their own identity.

Managing agents: in Settings → AI agents. This needs org owner or admin.

  • Create an agent and copy its API key. The key is shown once and stored only as a SHA-256 hash.

  • Add, rotate or revoke keys, optionally with an expiry. You can also disable or delete the agent.

What an agent can do:

  • Project access: an agent sees only the projects you switch on. For each project, toggle Read, Create items, Edit fields, Change status, Delete items, Comment, Read docs and Write docs.

  • Never allowed: agents can't administer projects, manage members or create projects.

  • Docs: a separate setting (none, read or write) covers org-wide doc spaces.

Attribution: everything an agent does is attributed to it.

  • The activity log and comments show a 🤖 avatar and an AI badge.

  • Teammates get live toasts ("🤖 Triage Bot moved APP-0012"), and assignees get notifications.

  • Each agent's settings page shows its recent activity.

MCP server: at /api/mcp (Streamable HTTP, stateless). Authenticate with Authorization: Bearer ml_….

Agents can upload media without a signed-in browser:

  • upload_media accepts name, mime, dataBase64 (canonical base64 bytes without a data: prefix, up to 1 MB), and exactly one of project or space. Use the project for any epic, milestone, story, task, subtask, or comment; use the document space for pages. Project uploads require item-create, item-edit, or comment permission; space uploads require document-write permission.

  • prepare_media_upload accepts the same scope and file metadata plus the exact byte size. It returns a single-use multipart POST URL valid for 10 minutes. POST the local file as field file with its declared MIME type; a browser cookie or extracted OAuth/API credential is not needed. Image limit: 20 MB; video limit: 200 MB. Keys, agent status, and current permissions are checked again when the ticket is used. Treat the temporary URL as a secret capability.

  • After HTTP 201 or a successful MCP upload, insert the returned markdown using create_item, update_item, add_comment, create_page, or update_page. Uploading alone does not attach the media to a description/page. Keep existing content and respect page versions. Images use normal Markdown image syntax; protected uploaded videos use [video](/api/uploads/<id>.webm) and render as video nodes.

  • read_media reads the relative upload URL through agent permissions. Complete images up to 1 MB include MCP image content; larger files can be read in chunks with offset, maxBytes, and nextOffset. Verify stored bytes and read back the target item/page before reporting success; this is not a substitute for a browser visual check when that is required.

  • Supported formats: PNG, JPEG, GIF, WebP, AVIF, MP4, WebM, OGG video, and MOV. SVG and other types remain unsupported. URLs stay protected: browsers use their file cookie, agents can use their API key for HTTP GET, and scoped uploads follow project/space read access. Existing browser uploads retain their organization membership access. Anonymous requests are denied. Reconnect existing MCP clients after deploying to refresh their tools.

Direct multipart POST /api/uploads also accepts agent API keys: send Authorization: Bearer ml_…, the file, and either a project or space field. Omitting Authorization produces 401; there is no need to automate a browser login.

Tools

Work

whoami, list_projects, get_project, search_items, get_item, create_item, update_item, move_item, delete_item, add_comment, list_members

Docs

list_spaces, search_docs, get_page, create_page, update_page (sends the version it read, so conflicting edits are rejected rather than overwritten)

Resources

mixedlane://items/{key}, mixedlane://projects/{key}/board

How the tools behave:

  • Descriptions, comments and pages are Markdown in and out.

  • Items are referenced by key (APP-12 or APP-0012), and statuses by name.

  • Every tool goes through the same services and permission checks as the REST API.

  • A denied action comes back as a readable tool error.

Agent plugins (recommended). Settings → AI agents → an agent → Connect → Install plugin. Mixedlane serves a plugin for each tool with this server's URL baked in, installed by a one-liner:

Choose a project when creating or authorizing a new agent. Project mode grants access to that project and disables project creation. Global mode is an explicit choice with a danger caption: the agent may create multiple projects; access to existing projects still requires grants. Existing agent connections retain their configured grants and show their scope at consent. Legacy API-created agents without a project start with no project grants and cannot create projects until an admin enables it.

Customize the organization skill: Settings → AI agents → Organization agent skill. Owners, admins and ordinary members can edit the shared Markdown instructions; guests can read them. This does not grant members access to agent identities, API keys or project grants. The default includes separate title/body boilerplates for epics, milestones, user stories, tasks, subtasks and bug reports, basic Markdown examples, and image/video upload-and-verification instructions. Preview a draft, save explicitly, or restore the default. Saves use a version check to prevent overwriting someone else's edits. Each organization has its own stored override. MCP provides get_agent_skill, and skills/hooks tell agents to refresh it before each new planning or ticket-writing request, so saved changes apply in ongoing sessions without reinstalling. Reconnect older clients once if that new tool is absent. Organization instructions do not change project permissions.

Install the plugin alongside MCP to get the hooks and four skills; the API-key and browser setup panels link back to this installation. Before creating any ticket, the skills search for similar active work in the same project and epic/milestone, update a match while preserving useful content, or create if none exists. Done/released tickets and tickets in other epics/milestones are excluded. create_plan automatically reuses exact title/type matches under the same parent and updates explicitly supplied fields; semantic matches are handled by the agent's search-and-update workflow. Re-run the installer to update existing installations.

curl -fsSL http://<host>/api/plugins/install.sh | sh -s -- claude-code        # or codex | copilot | opencode | pi
& ([scriptblock]::Create((irm http://<host>/api/plugins/install.ps1))) claude-code   # Windows PowerShell

Plugin

Contents

Install does

Claude Code

MCP (OAuth), 4 skills, mixedlane-planner agent, hooks (SessionStart, planning prompts, PostToolUse on ExitPlanMode), /mixedlane:plan · sync · start · done · init

claude plugin marketplace add + claude plugin install mixedlane@mixedlane

Codex

MCP (OAuth), 4 skills, hooks (SessionStart, UserPromptSubmit)

codex plugin marketplace add + codex plugin add mixedlane@mixedlane

Copilot (CLI + VS Code)

MCP (OAuth), 4 skills, planner agent, sessionStart hook

copilot plugin install (VS Code reads Copilot CLI's plugins)

opencode

MCP (OAuth), 4 skills, planner subagent, plugin (rules in the system prompt, mirrors todowrite plans), /mixedlane-plan

copies into ~/.config/opencode, merges opencode.json (backup kept)

Pi

MCP via pi-mcp-adapter (API key in MIXEDLANE_API_KEY), 4 skills, extension (rules in the system prompt), /mixedlane-plan

pi install npm:pi-mcp-adapter + pi install <dir>

Skills: mixedlane-planning (plans/requirements → epic → milestone → story (acceptance criteria) → task), mixedlane-work-tracking (start_work → keys in branches/commits → complete_work), mixedlane-docs, mixedlane-init (writes .mixedlane.json so every tool uses the same project). Re-run the installer to update; --uninstall / -Uninstall removes it. Verified end to end: a plain “make a plan for X” prompt in Claude Code, Codex and opencode created the epic/stories/tasks in the linked project.

Per-agent settings (agent page): Can create projects (on by default, subject to the delegating accounts' permissions) and When it plans work: Create items automatically (default) or Propose first (create_plan returns a preview until the user confirms). Denied actions name the exact setting to change.

Account permission ceiling. Every API key and OAuth token is limited to the intersection of its agent's configured permissions, the agent creator's current access, and the issuing/approving account's current access. Project roles, explicit revocations, document access and project creation are checked on each request; existing tokens follow later account changes. Removing either account from the organization disables the credential, and deleting the agent creator disables all its credentials. Agents creating a project give the delegating accounts creator access to that project. Migration 0014_agent_delegators binds older keys without an issuer to their known agent creator; credentials without a surviving creator remain unusable.

Planning tools: create_plan (a whole tree in one call, validated against the project's hierarchy first, idempotent — re-running reuses existing items), create_project, start_work, complete_work; MCP prompts plan and sync.

Two ways to connect

  • Browser sign-in (OAuth 2.1). Add just the URL; the client discovers Mixedlane's OAuth metadata (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server), registers itself (dynamic client registration) and opens a browser. An org owner/admin signs in, picks the agent to act as — or creates one with access to chosen projects — and clicks Allow. The client receives an agent API key named “OAuth · ”, revocable from the agent's page like any other key. PKCE (S256) is required and codes are single-use. Verified with opencode and an MCP-SDK client (the flow Copilot CLI / Claude Code use).

  • API key. Create a key on the agent's page and send Authorization: Bearer ml_….

Connecting a client. The agent's settings page (Connect) has a ready-to-paste setup for each of these, with your server URL filled in:

Client

How it connects

Tested here

Claude Code

claude mcp add --transport http mixedlane <url> --header "Authorization: Bearer ml_…"

✅

Claude Desktop

claude_desktop_config.json, bridged by npx mcp-remote

OpenAI Codex (CLI / IDE)

codex mcp add mixedlane --url <url> --bearer-token-env-var MIXEDLANE_API_KEY, or [mcp_servers.mixedlane] in ~/.codex/config.toml

✅ called whoami and list_projects over the LAN

GitHub Copilot (VS Code agent mode)

.vscode/mcp.json: an http server with "Authorization": "Bearer ${input:mixedlane-key}"; VS Code prompts for the key once

GitHub Copilot CLI

copilot mcp add --transport http --header "Authorization: Bearer ml_…" mixedlane <url>, or ~/.copilot/mcp-config.json

opencode

opencode.json → mcp.mixedlane with "type": "remote", "oauth": false, and "Authorization": "Bearer {env:MIXEDLANE_API_KEY}"

✅ opencode mcp list shows it connected

Pi

No built-in MCP support. Install pi install npm:pi-mcp-adapter, then add { "url": "<url>", "auth": "bearer", "bearerToken": "${MIXEDLANE_API_KEY}" } to ~/.config/mcp/mcp.json

Anything else

Any streamable-HTTP MCP client that can send an Authorization header

  • <url> is http(s)://<host>/api/mcp. In development either the API port (:3001) or the web port works.

  • Where the tool supports it (Codex, opencode, Pi), the setup reads the key from the MIXEDLANE_API_KEY env var so it doesn't end up in a config file.

  • Clients that send only Accept: application/json are accepted too.

  • Use one key per machine or tool, so each can be revoked on its own.

Beyond MCP, agents can also use the same API key for:

  • The REST API: any org-scoped endpoint; the key already names its org.

  • The realtime socket: io({ path: "/api/socket", auth: { token: "ml_…" } }) to react to changes live.

Docs

Confluence-style documentation that lives next to the work.

  • Spaces hold a tree of pages:

    • Org-wide space: members can write, admins manage it, and guests can't see it.

    • Project space: follows that project's access (viewers read, editors write, admins manage).

  • Page tree: drag a page onto another to nest it, or onto its top edge to reorder. Create sub-pages from the tree.

  • Templates: Blank, Product requirements, Technical spec, Meeting notes, Retrospective.

  • Editing: the same full-screen editor as items (Markdown, media, tables, @mentions). Ctrl+S saves.

  • Versions: every save is kept. History shows a word-level diff against the previous version. Restoring saves the old content as a new version.

  • Conflicts:

    • A save sends the version it started from. If someone saved in between, the API answers 409.

    • The page then shows both sides and lets you keep editing, discard your changes, or save anyway.

    • While you edit, a banner warns as soon as someone else saves.

  • Item links: item keys in a page (APP-12 or APP-0012) link it to those items. Each item shows a Linked pages panel.

  • Search: Postgres full-text search, weighting titles above body text, with highlighted snippets.

GitHub integration

Setup

  1. Settings → Integrations (sidebar): paste a GitHub personal access token.

    • Fine-grained tokens need these repository permissions:

      • Read: Metadata, Pull requests, Deployments, Actions

      • Contents: Read, or Read & write to create branches from items

      • Webhooks: Read & write (optional)

    • The token is checked against GitHub, then stored encrypted with AES-256-GCM. The key is in apps/server/data/secret.key in dev. Production must set SECRET_KEY (64 hex characters).

    • GitHub Enterprise Server works too: set the API URL.

  2. Project → Settings → GitHub:

    • Link one or more repositories. The first sync imports existing PRs, branches and commits but does not move any items.

    • Set up the automations.

Linking

Any mention of an item key links that GitHub object to the item:

  • branch names

  • PR titles and descriptions

  • commit messages

Keys are case-insensitive and zero-padding is optional: app-12 matches APP-0012.

Automations (per project)

  • Status triggers. Each trigger can move linked items to one of the project's statuses:

    • Branch created

    • Commit pushed

    • PR opened

    • PR merged

    • PR closed without merging

  • Deploy rules. Each rule moves every item that shipped in a deploy. It fires on one of three sources:

    • A GitHub Deployment succeeding (matched by environment, e.g. prod*)

    • An Actions workflow run succeeding on the default branch (matched by workflow name)

    • A release being published (matched by tag, e.g. v*; pre-releases are skipped)

    To find the items, Mixedlane compares the deployed commit with the previous successful deploy on the same line. For the very first deploy, it checks which merged PRs are ancestors of the deployed commit.

  • Only move forward (default on): items never move back to an earlier status.

  • Smart commits: APP-0012 #comment Fixed it #done adds a comment and moves the item. Any status name or id works as a command, e.g. #in-review.

  • The activity log records every automatic change, e.g. "GitHub · PR #12 merged" or "GitHub · deployed to production".

Delivery

  • Polling (default, works on localhost): every linked repo is checked on an interval you set (30 s to 15 min). Use Sync now to force a check.

  • Webhooks (instant): set a public URL, e.g. from cloudflared tunnel --url http://localhost:3001. Mixedlane registers the webhook itself when the token allows it; otherwise the page shows the URL and secret for manual setup. Signatures are verified with HMAC SHA-256.

  • Both paths feed one processor, which stores the last known state of every PR and deploy. An automation fires only on a real change, so duplicate deliveries, replays and polling overlap are safe.

Using it

  • C: create a work item from anywhere. Ctrl/⌘ K or /: search and commands.

  • Project tabs:

    • Overview: top-level items and anything due soon.

    • Board: Kanban of stories and tasks (or whichever work types the project uses), with drag and drop and filters.

    • List: expandable tree of the full hierarchy.

    • Settings: everything from the project form.

  • Click a card or row to open the quick-view side panel. Open takes you to the full page.

  • Everything is edited inline: title, description (Ctrl+Enter saves, Esc cancels), status, priority, assignee, labels, dates and estimate.

  • Allowed parents, statuses and item numbers are enforced by both the UI and the API (packages/shared/src/hierarchy.ts).

REST API

All routes are under /api. Request bodies are validated with the shared Zod schemas. The full interactive reference is at /api/docs (Swagger).

  • Sessions: access tokens last 5 minutes and are refreshed in the background; the refresh token renews on every use and expires after the user's Stay signed in for setting (Account settings: 30 days – 1 year) of inactivity. Network/server errors never sign you out — the app shows “Reconnecting…” and retries.

  • Auth: send Authorization: Bearer <accessToken> everywhere except the public auth and invite endpoints and the GitHub webhook.

  • Org scope: org-scoped routes also need X-Org: <org slug>.

POST   /auth/register | /auth/login | /auth/refresh | /auth/logout | /auth/logout-all
GET    /auth/me                        PATCH /auth/me    POST /auth/change-password
POST   /auth/forgot-password | /auth/reset-password | /auth/verify-email | /auth/resend-verification
GET    /invites/:token                 POST /invites/:token/accept
GET    /orgs                           POST /orgs         (yours / create)
GET    /org                            PATCH/DELETE /org  (current org via X-Org)
GET    /org/members                    PATCH/DELETE /org/members/:userId
GET    /org/teams                      POST /org/teams    PATCH/DELETE /org/teams/:id
POST   /org/teams/:id/members          DELETE /org/teams/:id/members/:userId
GET    /org/invites                    POST /org/invites  DELETE /org/invites/:id
GET    /projects/:key/access           PATCH/POST /projects/:key/access   DELETE /projects/:key/access/:grantId

GET    /projects                      POST /projects
GET    /projects/:idOrKey             PATCH/DELETE /projects/:idOrKey
GET    /projects/:idOrKey/tree        all items with roll-up progress
GET    /projects/:idOrKey/items?type=story,task&status=&parentId=root|<id>&q=
POST   /items                         GET /items/:id   GET /items/by-key/APP-0012
PATCH  /items/:id                     PATCH /items/:id/move {status, sortOrder}
DELETE /items/:id                     (cascades to children)
GET    /items/:id/activity
GET    /items/:id/comments            POST /items/:id/comments
PATCH  /comments/:id                  DELETE /comments/:id
GET    /search?q=

GET    /agents                        POST /agents  (→ agent + one-time key)   GET/PATCH/DELETE /agents/:id
POST   /agents/:id/keys               DELETE /agents/:id/keys/:keyId (revoke)
PUT    /agents/:id/grants {projectId, permissions[]}   GET /agents/:id/activity
POST   /mcp                           MCP endpoint (agent API key)
GET    /plugins                       plugin catalogue with install commands (public)
GET    /plugins/<client>.tar.gz       bundle with this server's URLs · /plugins/install.sh · /plugins/install.ps1
GET    /notifications?unread=true     POST /notifications/:id/read   POST /notifications/read-all
GET    /spaces                        POST /spaces       GET/PATCH/DELETE /spaces/:key
GET    /spaces/:key/pages             POST /spaces/:key/pages   (tree / create)
GET    /pages/:id                     PATCH /pages/:id {title?, contentHtml?, baseVersion} → 409 on conflict
POST   /pages/:id/move {parentId, beforeId?}      DELETE /pages/:id (cascades to sub-pages)
GET    /pages/:id/versions            GET /pages/:id/versions/:v   POST /pages/:id/versions/:v/restore
GET    /docs/search?q=                GET /items/:id/pages

GET/PUT/PATCH/DELETE /github/connection      POST /github/webhook (signed)
GET    /github/repos?q=
GET    /projects/:key/github                 POST /projects/:key/github/repos
DELETE /projects/:key/github/repos/:repoId   POST /projects/:key/github/repos/:repoId/webhook
POST   /projects/:key/github/sync            PUT  /projects/:key/github/automation
GET    /items/:id/development                POST /items/:id/github/branch
POST   /uploads (multipart "file")           GET  /uploads/:name (supports Range)

Every change is attributed to the signed-in user (or to GitHub, for automations) in the activity log.

Realtime socket: io({ path: "/api/socket", auth: { token, org } }).

  • Server → client: live (a LiveEvent: item, comment, project, space, page or notification) and presence ({ resource, users }).

  • Client → server: presence:join ({ resource: "item:<id>" | "page:<id>", mode }) and presence:leave.

Production

docker-compose.yml runs the app with external PostgreSQL. Use the standalone docker-compose.db.yml instead to include bundled PostgreSQL. Only the web container is published; everything is served from one origin.

Service

Image target

What it does

web

Dockerfile --target web (nginx, non-root)

Serves the built UI and reverse-proxies /api (REST, uploads), /api/socket (WebSocket), /api/mcp (MCP, streamed) and /.well-known (OAuth discovery). Strict CSP (app scripts and Cloudflare analytics only), security headers, long-cache hashed assets, index.html never cached.

api

Dockerfile --target api (Node, non-root, tini)

REST API, MCP server, realtime socket, job worker, agent plugins. Runs migrations on start. Internal only.

db (bundled stack only)

postgres:17-alpine

Data (volume pgdata). Internal only; included in docker-compose.db.yml.

minio (optional)

quay.io/minio/minio

S3-compatible uploads (--profile s3).

cp .env.example .env            # set DATABASE_URL and APP_URL (the public URL)
docker compose up -d --build    # → http://<host>:${HOST_PORT:-3000}
# with S3-compatible uploads on a bundled MinIO:
docker compose --profile s3 up -d --build

External PostgreSQL

To use your own PostgreSQL server, create a database and user, then set DATABASE_URL in .env:

DATABASE_URL='postgresql://mixedlane:encoded-password@db.example.com:5432/mixedlane?sslmode=verify-full'

Use your provider's TLS settings; sslmode=verify-full verifies the server certificate and hostname using a trusted CA. Percent-encode special characters in the URL's username and password. The database host must be reachable from the API container; localhost inside it refers to the container itself. For a database on the Docker Desktop host, use host.docker.internal.

Start the default stack:

docker compose config --quiet
docker compose up -d --build
# Add --profile s3 before up to also run bundled MinIO.

The default stack contains no bundled db service or database startup dependency. POSTGRES_PASSWORD is unused and can be empty; an empty DATABASE_URL fails Compose validation.

Migrations run automatically against the external database on API startup. The database user needs permissions to create and alter application tables and the drizzle migration schema. The external server must be ready before startup; check docker compose logs api and /api/health after launching. Pointing at a different database does not copy existing data.

Bundled PostgreSQL

Set POSTGRES_PASSWORD in .env to a strong URL-safe value (for example, a generated hex string), then use the standalone bundled stack:

docker compose -f docker-compose.db.yml config --quiet
docker compose -f docker-compose.db.yml up -d --build
# With bundled MinIO uploads:
docker compose -f docker-compose.db.yml --profile s3 up -d --build

This starts PostgreSQL 17 and waits for its health check before starting the API. It builds the internal connection URL from POSTGRES_PASSWORD, ignoring any external DATABASE_URL in .env. An empty password fails Compose validation. Data persists in pgdata; changing the password in .env does not change credentials in an existing database volume. Use -f docker-compose.db.yml for subsequent commands such as logs and down; this file is used on its own, without merging it with docker-compose.yml.

If switching an existing installation, stop its stack first using the original Compose file (for example, docker compose -f docker-compose.db.yml down for bundled mode), keep its volumes, and migrate your data separately before starting against the new database. Both files use the same Compose project name and are alternatives for one deployment. If upgrading from the previous default that bundled Postgres, stop that stack with its original file before replacing it.

  • HTTPS: put any TLS proxy (Caddy, Traefik, a cloud load balancer) in front of web, set APP_URL=https://… (turns on Secure cookies + HSTS) and TRUST_PROXY=2. nginx passes the proxy's X-Forwarded-Proto through.

  • Single container instead: docker build -t mixedlane . builds the default app target — the api also serving the UI (WEB_DIST) — and needs only DATABASE_URL plus the secrets.

  • Verified: the compose stack was built and smoke-tested through nginx only: health, SPA deep links, strict CSP (no violations in the browser), register/refresh cookie, uploads, WebSocket realtime, OAuth discovery and plugin installers on the public URL, and an agent creating a project and a plan over MCP with the team seeing it live.

Build and startup

  • Images: one multi-stage Dockerfile builds the web app (Vite) and compiles the API (SWC), producing the api, web and app targets.

  • Runtime: production dependencies only, running as the non-root node user under tini, with a health check.

  • Migrations: run automatically on start.

Required configuration

  • DATABASE_URL, plus JWT_SECRET and SECRET_KEY (64 hex characters).

  • The Docker images set SECRETS_DIR=/data/secrets: when the two secrets are left empty, they are generated on first start and kept on the /data volume (back it up, or set them in .env).

  • Outside Docker, the server refuses to start in production without them unless SECRETS_DIR is set.

Uploads

  • STORAGE_DRIVER=local: a volume at /data.

  • STORAGE_DRIVER=s3: any S3-compatible bucket (AWS, MinIO, R2, Spaces) via S3_BUCKET, S3_REGION, S3_ENDPOINT and S3_FORCE_PATH_STYLE. Credentials come from the keys or the default AWS chain.

  • Files stay private and are streamed through the API, with range support.

Security

  • A strict Content-Security-Policy on the web app: scripts come only from the app itself, a hashed inline theme snippet, and https://static.cloudflareinsights.com for the proxy-injected analytics beacon. Analytics reports may connect to https://cloudflareinsights.com; no wildcard script sources or unsafe script execution are allowed.

  • frame-ancestors 'none', nosniff, and the other helmet defaults.

  • HSTS and Secure cookies are turned on automatically when APP_URL is https://.

Rate limits

  • API_RATE_LIMIT requests per minute per client (agent key or IP) across the API.

  • Stricter per-IP limits on login, registration and password reset (AUTH_RATE_LIMIT).

  • Limits are kept in memory per instance.

Behind a reverse proxy

  • Set TRUST_PROXY (e.g. 1) so client IPs are correct.

  • Forward WebSocket upgrades for /api/socket.

Health check: GET /api/health checks the database too.

Graceful shutdown: on SIGTERM, sockets, the job worker and the DB pool close cleanly.

Excluded in production: the dev-only demo seeding and reset endpoint.

Scaling beyond one instance: later work will add the socket.io Redis adapter, a shared rate limiter, and BullMQ in place of the DB job queue. The job queue already works across instances (FOR UPDATE SKIP LOCKED).

Verified:

  • The full test suite passes against PGlite and against Postgres 17.

  • A smoke test against the compose stack passed: health, SPA and CSP, registration, docs search, S3 upload and range reads, an agent over MCP, and live socket delivery.

Mixdi in-app creation agent

Owners and admins configure Settings → Mixdi: enable the assistant, reuse WhatsApp AI providers or configure dedicated providers, select allowed users (including admins), and allow ticket/document creation in explicitly selected projects/spaces. Empty user or destination selections grant no access. Credentials are encrypted at rest and never returned to the browser. Mixdi always acts within the signed-in user's current permissions.

Use Models & testing to test one provider or all configured providers. Each test sends a small synthetic prompt through the same adapter used by chat and validates the JSON response, reporting latency and actionable failures. Dedicated tests include unsaved model/credential edits and preserve saved keys when omitted; shared tests use the existing WhatsApp configuration. Tests may consume provider quota, but never save settings or create tickets, documents or chat history. Access & capabilities provides searchable user, project and space selections; save explicitly to apply changes.

Open Mixdi in the sidebar, choose a destination and optional parent, then chat to create and refine a draft. Review the draft and select Create to save it. LangChain handles provider fallback and LangGraph runs drafting and validation. Draft creation is scoped to its author and retries are idempotent; drafts expire after 24 hours. Conversations and drafts are saved privately per user and organization. Reopen recent chats from the history sidebar (or the history button in the floating panel), continue drafting, or start a new chat. The parent-level selector filters tickets by the project hierarchy. The floating Mixdi button opens chat without leaving the page and uses the current ticket as parent, including quick-view tickets. Leaf tickets cannot be parents. This release has no retrieval tools. TODO: embeddings and semantic search (MIX-0029), then ticket/document search, summaries and research (MIX-0030).

WhatsApp intake and AI triage

Owners and admins configure Settings → Integrations → WhatsApp with an OpenWA gateway URL and API key, plus a Mixedlane base URL reachable from that gateway. Link an existing OpenWA session, or add an account and scan its QR directly inside Mixedlane. The integration targets OpenWA's session-based REST API (/api/sessions, verified against v0.24.0), not the separate @open-wa/wa-automate API.

Map team phone numbers (full country code) to organization members. Only direct messages from mapped current members trigger intake. Send APP Login fails after reset to choose a project directly, or send a report and choose from the project list. In WhatsApp settings, select a default project to skip the project menu, or leave it blank. With no default, enable “Ask for a project for every report” to keep asking, or turn it off to reuse each sender’s last project per connected WhatsApp account. Project-code prefixes override these defaults. A single eligible project is selected automatically. Project permissions apply to defaults and remembered choices, during AI triage, and at approval.

LangChain tries Ollama Cloud → Gemini → Grok (xAI) → OpenAI → Custom provider in order, skipping unconfigured providers. Configure model names and credentials for each provider; Ollama's direct cloud API uses the name listed by https://ollama.com/api/tags (for example gemma4:31b). For OpenAI, enter a model name and API key. Custom providers accept a full OpenAI-compatible chat completions URL (for example https://provider.example/v1/chat/completions), model name, and API key. The OpenAI-compatible request format follows the OpenAI Chat Completions API. Provider HTTP failures, malformed JSON, and invalid hierarchy proposals trigger fallback. The AI decides the enabled work item type, parent, priority, category and description, with possible duplicates flagged for review. Existing project items are supplied as context, capped at the 200 most recently updated items; this is not an exhaustive duplicate search.

The sender can create, edit, or cancel from the WhatsApp preview. Quoted replies such as yes, cancel, or additional details review or refine the same draft. Admins can approve or cancel from the app's draft queue and retry failed AI generation. Approval creates the ticket and closes the draft in one database transaction, so concurrent approvals create one ticket. Reports and signed webhook events are deduplicated by session and message ID. Incoming events, AI work, and notifications use the existing database job queue. While handling messages and generating AI drafts, Mixedlane calls OpenWA’s /api/sessions/:id/chats/typing presence endpoint, refreshes typing every eight seconds, and sends paused when processing finishes or fails. Presence errors do not fail report processing.

AI failures include a diagnostic reference in the draft queue. Administrators can search the server's AIIntegration logs for that reference: JSON records correlate the organization/draft, provider/model, attempt, timestamp, duration, HTTP status, safe provider code, failure category, fallback, and final outcome. Raw prompts, responses, provider error bodies, authorization headers, and credentials are excluded. These diagnostics use the deployment's server-log access controls and retention; Mixedlane does not store a separate diagnostic history.

Button/list sends require a compatible OpenWA engine (the verified API documents Baileys). Unsupported-engine responses fall back to quoted text commands; text commands also appear in previews for clients that do not render buttons. The integration sends idempotency headers supported by the gateway; delivery retry guarantees depend on its version. Screenshots and voice transcription are not processed by this initial text intake.

Credentials are encrypted with Mixedlane's SECRET_KEY and never returned by settings endpoints. Leave saved key inputs blank to retain them. To provision encrypted defaults on a local installation, set OPENWA_API_KEY, OLLAMA_API_KEY, and optionally OPENWA_URL / OLLAMA_MODEL in the process environment, then run node --import @swc-node/register/esm-register ../../scripts/configure-whatsapp.mjs from apps/server. This writes only encrypted values into the ignored apps/server/data/whatsapp-bootstrap.json; organization settings take precedence. Preserve the encryption key and data together when moving the installation. Tests ignore these defaults.

For LAN delivery, the gateway must be allowed to reach the configured callback host; OpenWA's webhook URL policy may require that host in SSRF_ALLOWED_HOSTS. Newly created sessions belong to Mixedlane and are deleted when removed here. Linking an existing session adds a webhook; removing that link preserves the existing OpenWA session.

Roadmap

  • Phase 3 — Realtime ✅ live updates, presence, notifications inbox

  • Phase 4 — Docs ✅ spaces, page tree, templates, versions, conflicts, item links, search

  • Phase 5 — AI agents ✅ agent identities, API keys, per-project toggles, MCP server

  • Phase 6 — Production ✅ Docker + Postgres, S3 storage, CSP/rate limits/health, compiled build

  • Next ideas: OAuth sign-in, the Redis adapter for multi-instance realtime, BullMQ, and webhooks out to other tools.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to look up stored logins by URL, name, or alias and use them without seeing the secrets, injecting authentication into HTTP requests, running commands with credentials in the environment and scrubbed output, and fetching 2FA codes, subject to per-credential policies and user approval.
      23
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to track time, manage the project board with epics, milestones, schedules and dependencies, and generate shareable reports through a single authenticated connection.
      MIT