MCP Setup

Install the released CLI

• Operalta is distributed as a GitHub Release asset, not through the public npm registry. The installer installs both operalta and operalta-mcp into ~/.local/bin.
• The MCP server uses local stdio. There is no hosted MCP URL to add with an HTTP or SSE transport.
• Sign in with the MCP OAuth flow before connecting a client.

curl -fsSL https://www.operalta.ai/install.sh | sh
source ~/.zshrc
operalta login --mcp
operalta-mcp --help

Configure a client

• Recommended for Claude Code: run operalta install --target claudecode from a built checkout. It registers the server in ~/.claude.json, adds a managed workflow block to ~/.claude/CLAUDE.md, and ships /operalta-context and /operalta-debrief command files — merging into files it does not own and never overwriting content it did not create.
• The installer writes the server entry as an absolute path to the built file rather than the operalta-mcp binary name shown in the manual example below: Claude Code launches MCP servers with its own spawn environment, which may not carry ~/.local/bin on PATH, so pointing at the file directly is the safer default.
• Manual fallback (or for Cursor, Windsurf, and other clients): add operalta-mcp as a local stdio MCP server by hand. Do not use npx @operalta-ai/cli.
• OAuth is the default authentication path either way: run operalta login --mcp once and let the server reuse that local session. It keeps user identity and granted scopes explicit.
• OPERALTA_API_KEY is a secondary fallback for headless or server-to-server installations where browser OAuth is unavailable; do not add it to a normal desktop MCP configuration.
• OPERALTA_COMPANY_ID pins a company in multi-company setups.

operalta install --target claudecode

Run from a repository checkout

• Contributors can run the MCP server directly from TypeScript source. This does not require a compiled dist/ directory.
• Point the client at the checkout-local tsx executable and the MCP entrypoint. This tracks the current branch, so use it for development rather than a stable deployment.

{
  "mcpServers": {
    "operalta": {
      "command": "/absolute/path/to/operalta-app/node_modules/.bin/tsx",
      "args": ["/absolute/path/to/operalta-app/packages/operalta-mcp/src/cli.ts"]
    }
  }
}

Tool families

• Read: get_company_context, get_metrics, get_decisions, search_knowledge, get_structure.
• Metrics: get_metric_definitions, get_metric_history, compare_metrics, and get_company_performance read and analyse company-internal actual, budget, and forecast series. import_company_actuals previews or imports actuals through the canonical Collect path.
• Published portfolio metrics: get_portfolio_metrics and get_portfolio_cohort_metrics read only report snapshots covered by an active grant; they never blend in a startup's live internal metrics.
• Artifacts: sync_artifact, get_artifact, archive_artifact.
• Office: operalta excel create <spec.json> creates a local .xlsx file as an explicit user-invoked CLI command without calling the Operalta API.
• Innovation templates: operalta excel template create <template-id> produces ready workbooks for portfolio, scoring, experiments, roadmap, funding, partners, impact metrics, and venture BP. The former model-facing Excel tools are retired.
• Lists & matrices: create_list, create_matrix_from_template, get_list, upsert_list_entries — read and maintain strategic matrices with the scopes granted to the OAuth session or company key.
• Automation: list_automation_methods, activate_goal_loop, list_goal_loops, and step_goal_loops expose the governed Method → Matrix → Loop workflow without bypassing admin activation or human checkpoints.
• Agents: council, panel, research_panel, and deep_research; use explicit operalta agent commands for advanced canonical runs. The legacy orchestrate model tool is retired.
• Workflow: pipeline, Transporter room resources, and deferred host-local data-room scan, gap analysis, and consent-gated build. Hybrid room-sync model tools are retired; explicit Transporter and room upload operations own tenant persistence.
• Financial planning: read company context and metrics, then create artifacts or room outputs that reference the same company-scoped source data as FounderFin.
• Community Rooms are not in the current MCP tool pack. They will use a separate Network context and must never fall back to Company data.

Analyse metric history over MCP

• Call get_metric_definitions first when labels, units, or custom metrics are not already known. The result carries the company currency and the canonical identifier for each metric.
• Use get_metric_history with one explicit grain — month, quarter, or year — and optional actual, budget, or forecast versions. Queries are bounded and cursor-paginated; follow nextCursor instead of guessing a period after the last row.
• compare_metrics compares two periods deterministically. get_company_performance adds the latest trend and, when requested, actual-versus-budget or actual-versus-forecast variance with missing-data states and formulas.
• import_company_actuals uses the same company-scoped Collect path as the product import. It defaults to a dry run; set dry_run: false only after reviewing the detected periods and validation result.
• Internal history comes from company_metrics. Investor reads use get_portfolio_metrics or get_portfolio_cohort_metrics and remain on frozen published snapshots. Historical portfolio periods appear only when the grant allows history.
• Reading actuals requires metrics.actuals:read; reading budgets or forecasts requires metrics.plans:read. The authenticated OAuth workspace supplies the company boundary.

Create a recurring workflow over MCP

• Start with list_automation_methods. By default it returns only Methods that support managed execution and are compatible with the current identity and scopes.
• Create a Goal Loop Matrix and the Method output Matrix with create_matrix_from_template, then add the Loop row with upsert_list_entries. For example, a monthly market read can write each new result into its radar Matrix.
• An admin activates the row with activate_goal_loop, passing the stable method_ref, Loop row, and output Matrix. The row must already contain its trigger and maximum iteration count.
• Weekly and monthly cadences can continue automatically. Manual work is advanced with step_goal_loops; a dry run reports whether the next step is allowed before anything is queued.
• The event trigger is part of the Method contract but needs a concrete event producer. It is not a generic automatic trigger today, and neither MCP nor REST calls can bypass a Loop waiting for human instructions.
• Read access uses lists:read. Creating Matrices uses lists:write; activation and stepping require lists:write plus agents.runs:write. Managed activation also requires company-admin access.

Your oversight surface from the terminal

• The matrices you pilot in the app — bets, theses, term sheets, portfolio monitoring — are fully readable and maintainable over MCP, so a terminal or desktop AI session works the same board your team sees.
• A typical loop: explore your codebase or documents in the session, then push the conclusions into the matrix — new entries, updated cells, moved stages — instead of losing them in the chat scrollback.
• Specs and long-form conclusions belong in artifacts (sync_artifact); the matrix keeps the state and telemetry. That split is what makes the board reviewable by the whole team.
• Everything an assistant writes through MCP respects the same rules as the app: your hand-edited cells are never overwritten, and every write is scoped to the company on the key.

Company context

• OPERALTA_COMPANY_ID pins MCP calls to one company when your key can access multiple workspaces.
• Financial tools are company-aware: a founder workspace, investor workspace, and portfolio workspace can expose different metrics, labels, and workflows.
• Use the same company context when moving between CLI, MCP, and REST API calls so forecasts, artifacts, and rooms stay attached to the intended workspace.

Spreadsheet automation boundary

• For local work, use operalta excel create or operalta excel template create to produce the workbook on disk. These are explicit CLI commands, not model tools. This path does not require OPERALTA_API_KEY and does not create a server-side generated export.
• Pick the template by company type and job: startup experiments/BP, fund or accelerator portfolio, corporate roadmap/capacity, public sector or nonprofit impact/funding, and partner ecosystem tracking.
• Template IDs include innovation_portfolio, opportunity_scorecard, experiment_tracker, roadmap_capacity, funding_plan, partner_ecosystem, impact_metrics, and venture_bp.
• Use the office_spreadsheet sandbox path when an agent must generate the workbook server-side, promote it into Operalta storage, or link it to Rooms from the web app.
• Keep OPERALTA_COMPANY_ID pinned when API-backed follow-up is needed so workbook assumptions, labels, room access, and generated exports stay tied to the intended company type.