Debreu MCP Server

Connect your AI assistant to Debreu to query deal intelligence, manage companies, contacts, tasks, and metrics directly from Claude, Cursor, or any MCP-compatible client.

Quick Start

1. Get an API Key

Log into Debreu, click your avatar in the top-right corner, and go to Account Settings. Under API Keys, generate a new key. Copy it immediately — it cannot be retrieved again.

2. Configure Your Client

No install needed — npx downloads and runs it automatically.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "debreu": {
      "command": "npx",
      "args": ["-y", "debreu-mcp"],
      "env": {
        "DEBREU_API_KEY": "dbr_your_key_here"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "debreu": {
      "command": "npx",
      "args": ["-y", "debreu-mcp"],
      "env": {
        "DEBREU_API_KEY": "dbr_your_key_here"
      }
    }
  }
}

Cursor

Go to Settings > MCP Servers > Add, then:

• Name: Debreu
• Command: npx -y debreu-mcp
• Environment: DEBREU_API_KEY=dbr_your_key_here

ChatGPT

ChatGPT requires a remote HTTPS MCP endpoint (it does not support local servers). To connect:

1. Deploy the Debreu MCP server as a remote HTTP endpoint (e.g. using mcp-remote or a cloud host)
2. In ChatGPT, go to Settings > Apps > Create (requires Developer Mode — available on Business/Enterprise/Edu plans)
3. Enter the remote endpoint URL and configure authentication
4. Click Create, then test and publish

See OpenAI's MCP docs for full setup details.

Available Tools

Prospecting-only tenants see a different, narrowed catalog — the eight Prospecting-only tools plus the three comment tools — and none of the tools below. tools/list is filtered automatically based on the account's prospecting_only flag.

Agents (feature-gated)

These four tools appear only when the authenticated user's view_agents flag is enabled. They are unavailable to prospecting-only accounts. Backend checks also enforce the flag on every request, so stale discovery cannot bypass revocation. Discovery caches capabilities for up to 60 seconds; reconnect/refresh the tool list after enabling access.

| Tool | Description | |------|-------------| | create_agent_run | Start travel planning with destination, dates, timezone, meeting duration, and buffer, optionally for a teammate (for_user_id). | | list_agent_runs | List compact summaries with pending-work counts, processing state, and app links; paginate with limit/offset and optionally filter by status. | | get_agent_run | Inspect full companies, contacts, drafts, conversations, meetings, processing state, revisions, executable MCP actions, and external send links. | | update_agent_run | Typed approve, remove, retry, add_companies, edit_draft, set_status, retry_run, or update_settings action. |

Read the run before changing it. Bulk approval selects companies and contacts together and only creates drafts. Supply the returned revisions and a stable request ID for identical bulk retries. add_companies accepts CRM company UUIDs and reports partial success. Draft edits require the draft ID/revision and item revision. Run lifecycle changes require the run revision. Read-only MCP credentials can list/get but cannot mutate runs.

As of 2.158.0, list_agent_runs returns {runs, total, limit, offset, has_more, next_offset} (default 20, maximum 100), not a full-run array. Each run includes url, summary counts, item_status_counts, and processing. Full email bodies, contacts, and activity are available through get_agent_run. summary.draft_sends counts only unsent saved drafts, excluding emails already sent but not yet reconciled.

When processing.pending or processing.reconciliation_pending is true, item statuses and holds may still reflect the last processed state. Poll get_agent_run again; do not resend an email whose draft status is sent. A paused run exposes queued work and instructs the user to resume. Item send_tracking_pending identifies a sent email awaiting tracking. allowed_actions contains executable MCP item actions; app-only sending is listed separately under external_actions, including its canonical URL. A 409 conflict instructs the caller to reread and review current IDs/revisions before retrying.

There is no send action: emails must be sent by the user through Debreu, Gmail, or Outlook. Calendar holds and reply tracking remain owned by the agent runtime. Deploy the backend and this MCP server together to enable the tools; no new database migration is needed for MCP access.

Companies

| Tool | Description | |------|-------------| | lookup_company | Look up a company by name, UUID, or website. Returns profile, latest metrics, and current-user interaction dates. | | query_companies | Filter companies by metric values, company tags, or current-user interaction dates with AND logic. Supports string, numeric, and existence operators. Tags use the same filters array as every other field. | | create_company | Create a company (requires name, website). Auto-hydrated with enrichment data. | | update_company | Update company name and/or set metric values by UUID. Accepts a metrics array of {metric_name, value} pairs. |

Metrics

| Tool | Description | |------|-------------| | get_metric_schema | Get available metric definitions (names, types, categories, and allowed_values for enum metrics — call before setting a metric so you write a valid value). Interaction date fields are queryable separately from metric schemas. | | query_metric_history | Find companies where a numeric metric changed significantly over a date range. History rows carry temporal-identity fields (observed_at, value_date, period_start/period_end, period_label, flavor = actual/projection/guidance). |

People

| Tool | Description | |------|-------------| | lookup_person | Look up a person by name, email, or UUID. Returns profile (incl. IANA timezone auto-extracted from signatures), company, relationship data (interaction dates, scores), tags, origin, and the people graph: roles (dated career history) and education. Each row carries evidence — filed / extracted / user. | | get_people | Search contacts tenant-wide or at an optional company, with search, relationship-score/date/name sorting, pagination, explicit current-user score, team scores, and tags. | | create_person | Create a person (requires name; company_id optional — omit for contacts with no employer). Optional fields include phone, linkedin_url, role, location, timezone (IANA, e.g. America/New_York), and do_not_contact / do_not_contact_source (contact suppression; source defaults to the current user's name). | | update_person | Update person fields by UUID (only provided fields are changed). Supports the same optional fields as create_person, including linkedin_url and do_not_contact / do_not_contact_source. | | manage_person_education | List, add, update, or remove a person's education (list / add / update / remove). Replaces the removed alma_mater field — a person can hold several degrees. | | manage_person_career | List, add, update, or remove a person's dated career history, including board seats. Replaces the removed previous_company field. Dates accept YYYY, YYYY-MM or YYYY-MM-DD; the stored precision follows what is passed. | | manage_company_contacts | List, add, update, or remove people scoped to a project participant company or tracker-company row. |

Team

| Tool | Description | |------|-------------| | get_team | Get team members (uuid, name, email). Use to discover valid assignee_id values for tasks. |

Tasks

| Tool | Description | |------|-------------| | get_tasks | Query tasks with filters (supports project_id and company_id). Company-filtered queries exclude project-attributed tasks by default (include_project_scoped opts in). Returns description, status, due_date, pending_from, assignee, company, person, project, and source. | | create_task | Create a new task (requires description). Assignee defaults to current user; call get_team for other UUIDs. | | update_task | Update a task by UUID (only provided fields are changed). |

Projects

| Tool | Description | |------|-------------| | query_projects | Search projects (deals) by client, company membership (participant, tracker, or any), type, status, or date. Company-filtered results include membership details plus codename, scope, coverage_group, participants, and canonical tracker-tab URLs. | | get_project | Get full project details including codename/scope/coverage_group, participants (deal parties with roles, primary flagged), tasks, trackers with canonical tracker-tab URLs, tracker accounts (companies with their per-tracker deal_role and counterparty fields, or people with interview details for up to 8 rounds, depending on type), working group roster, key dates, generated companies, and deal_term_fields (the deal-term fields the project's deal type uses, with unit, meaning, enum options and current value). | | create_project | Create a project with one or more trackers via the trackers array (at least one required; a dual-track deal passes two, e.g. buyer_universe + investor_outreach). Each tracker carries its own type (acquisition_targets, buyer_universe, outreach, investor_outreach, company_list, people_list, prospecting, sector_initiatives, opportunities, coverage, conference_trip_ndr) plus optional configuration and seed lists (conference_trip_ndr takes a location and auto-generates a ranked list of tracked companies in that metro). Optional tev (millions, in tev_currency: USD/EUR/GBP/CAD) / fees ($M, always USD) and participants with nested contacts are stored on the project (success_probability is status-derived, not writable). | | add_tracker | Add one tracker (board) to an existing project after creation (project_id + the same per-tracker config as a create_project trackers[] entry). | | update_project | Update project fields, including deal terms (fee ladder, retainer, kicker, minimum fee, valuation, tenor, expenses; each field states the deal types that use it and a write outside them returns a warning; fee terms hidden for fee-restricted users; success_probability is status-derived, not writable), replace participants and their nested contacts, edit participants individually, and manage trackers, accounts, working groups, and key dates. | | link_to_project | Manually attach an email, file, or calendar event to a project (entity_type ∈ email/file/calendar). Stamps method='manual' and revives a previously rejected link. | | unlink_from_project | Remove an email, file, or calendar event from a project. Removal is sticky — automated linking will not re-create it. |

Deal Memos

| Tool | Description | |------|-------------| | get_deal_memo_templates | The memo types this tenant has, with every field's key, type and allowed values. Read it before writing: templates are tenant-seeded, so field keys and enum vocabularies are not knowable otherwise. Percents are stored as decimals (2% = 0.02); a bound or readonly field is filled from the deal, the client company or the working group. Pass project_uuid for can_create per template. | | get_deal_memo | A deal's memos, or one in full — stored values, computed cells, sign-offs, and a workflow block whose can_* flags say which review actions this user may take now. | | create_deal_memo | Write a memo of one type for a deal. Refused when the deal has not reached that stage, or already has one of that type. | | update_deal_memo | Set some of a memo's fields. Sparse — only the keys sent are touched. A bound field writes through to the deal or client company in the same transaction. Metric fields can state several periods as a list of {period, value} entries. | | manage_deal_memo_review | Circulate a memo to the deal's working group, approve it, or reject it back to draft with a reason. Steps cannot be skipped and rights are enforced: only a working-group member circulates, only the deal lead passes it up, only an authorized committee member signs off. Committee approval advances the deal when it is still parked at that memo's gate. Sends email. |

Comments

| Tool | Description | |------|-------------| | query_comments | Get comments on a record by data_model (task, company, person, workflow, project, file, prospecting_public_company, prospecting_portfolio_company) and record_id. For companies, also returns comments on other records that @mention the company (with a mention_context saying where the comment lives). | | create_comment | Add a comment to any commentable record (same data_model set as query_comments, including prospecting-list rows). | | update_comment | Update a comment's content by UUID (author only). |

Sentiments

| Tool | Description | |------|-------------| | get_sentiments | Query sentiment signals extracted from emails, files, and calendar events. Supports project_id; company-filtered queries exclude project-attributed sentiments by default (include_project_scoped opts in). |

Deal Signals

| Tool | Description | |------|-------------| | query_deal_signals | Query the deal-signal store — the full ~44-type catalog: process state, intent, bid & deal economics (indicated_amount/indicated_multiple), counterparty milestones (passed_date/passed_by), deal terms/characterization, ECM fields — with search/sort/pagination. Filters: company_id, project_uuid, signal_type, include_project_scoped (company queries exclude deal-scoped rows by default), exclude_deal_level. Lists every observation (use get_deal_signal_history for one group's chain). | | get_deal_signal_history | Full supersession history for one signal group (company × project × signal_type) by any row UUID, newest-first; the current value is the entry flagged is_latest. | | set_deal_signal | Manually set/override any catalog signal value (company_id, signal_type, value, optional project_id); enum/multiselect types accept only their fixed slugs. Stored as a user-sourced value that outranks AI extraction (a re-parse won't overwrite it); logged to the company + project activity feeds. |

Entity Tags

| Tool | Description | |------|-------------| | set_entity_tags | Set tags on a record (email, calendar, file, person, company). Replaces existing tags with the provided list. | | bulk_tag_entities | Add and/or remove a set of tags across many records of one type at once. Reconciled per record (skip duplicate adds, ignore absent removals). Idempotent. |

Emails

| Tool | Description | |------|-------------| | query_emails | Search emails by keyword, date, company, project, person, or tag. Use 'me' for current user. | | get_email | Get full email content and tags by UUID from a query_emails result. |

Calendars

| Tool | Description | |------|-------------| | query_calendars | Search calendar events by date, company, project, person, keyword, or tag. | | get_calendar | Get full calendar event details and tags by UUID from a query_calendars result. |

Files

| Tool | Description | |------|-------------| | query_files | Search uploaded files and email attachments by upload date (created_at), company, project, keyword, or tag. Results include the semantic document_type and its document_category. | | get_file | Get full file content by UUID from a query_files result. Includes the semantic document_type and its document_category. | | upload_file | Upload a file via local path (stdio servers only — the hosted HTTP server rejects file_path, send content_base64) or base64 content. Supports title, description, company/calendar-event association, and file_date (backdate to a past document's effective date — parsing uses this as the reference date). | | share_file_with_user | Grant explicit access to a teammate for a file you own. Recipient gets full owner-equivalent access. | | share_file_with_users | Grant explicit access to multiple teammates in one call. | | list_file_shares | List all active shares on a file (explicit + email_recipient). Owner-only. | | revoke_file_share | Revoke an explicit share. Email-recipient and project-member shares cannot be revoked manually. |

Briefings

| Tool | Description | |------|-------------| | get_my_day | Get today's agenda, key meetings, action items, and priorities. | | get_my_week | Get the week ahead including meetings, deal updates, and deadlines. | | get_meeting_prep | Get AI-generated meeting prep for a company: background, metrics, talking points. |

Status Definitions

| Tool | Description | |------|-------------| | get_status_definitions | Get allowed status values for a status type (task, project, etc.). Call before filtering or setting status. |

Dashboard

| Tool | Description | |------|-------------| | get_dashboard_config | Get a dashboard config — by effective type ('home'/'custom') or by UUID. Returns layout and components, including dashboard widget config such as biopharma_catalyst_calendar. Documents the filter operator vocabulary (in/not_in, contains/not_contains, is_empty/is_not_empty, numeric/date comparisons + between) and the valid column/sort_by keys for the projects and companies widgets. | | list_dashboards | List all dashboards owned by the user, optionally filtered by type ('home', 'custom'). | | create_dashboard | Create a new dashboard (defaults to type 'custom') with a name and optional layout/components. | | delete_dashboard | Delete a user-level dashboard by UUID. | | update_dashboard_config | Update a user-level dashboard config by UUID. Supports name, 18-column layout, and components. tracker (set workflow_id; table-only, accepts tracker column keys incl. di_signal_*) and project_activity (set activity_source = starred / my_projects / manual, plus project_ids for manual) are documented in the tool. For biopharma_catalyst_calendar, use the documented column/filter keys and lowercase phase values. Pipeline widgets (flash_kpis, pipeline_waterfall, stage_count, pitch_outcomes, closed_ytd, pipeline_detail) show the pipeline report's numbers; they and sector_prospects, sponsor_scorecard are config-less except pitch_outcomes (outcome, rolling_days) and sponsor_scorecard (window_years); the six pipeline widgets also accept team_lead_user_id ('me') + scope_mode (team_lead=lead, working_group=shared). |

Issue Reports

| Tool | Description | |------|-------------| | report_issue | File a bug report about the Debreu product on the user's behalf. Only when the user asks to report a problem — not a scratchpad for agent notes or progress. |

Portfolio

| Tool | Description | |------|-------------| | get_portfolio_data | Read a company's holdings and funds — portfolio companies, subsidiaries, strategic stakes and credit alike — or a fund (sponsor + port_cos). port_cos = what this company owns; parent_portfolios = who owns it. Each row carries kind, entry_date, exit_date (absent = open), stake_pct, instrument, plus relationship_uuid and legacy relationship_data. Holdings carry history, so one pair can appear more than once. Deal lead and priority are company metrics now (owner/priority on the port_co company), not port_co fields. | | update_portfolio_data | Single write tool for holdings and funds. action ∈ create_port_co \| update_port_co \| create_fund \| update_fund. Both companies must already exist for create_port_co, which ADDS a holding (history is kept, so a pair may recur). Holding fields: kind (buyout, minority, subsidiary, credit; PE vs VC lives on the firm's buyer_investor_type), entry_date, exit_date (set it to CLOSE a holding rather than deleting it), stake_pct, instrument (equity/debt); stake_type is deprecated. Funds carry a sponsor-relative strategy (flagship, growth, venture, lower_mid_market, opportunities, credit, special_situations, continuation, secondaries, co_invest, sector, regional, real_estate, infrastructure, impact, long_hold, other); omit on create to infer from the name. |

Biopharma Assets

| Tool | Description | |------|-------------| | get_biopharma_assets | Read biopharma assets and nested indications for biotechnology or pharmaceuticals companies by company_uuid or asset_uuid. | | create_biopharma_asset | Create a biopharma asset with optional target, mechanism of action, and lead flag. | | update_biopharma_asset | Update a biopharma asset by UUID. Nullable fields can be cleared with null. | | create_biopharma_indication | Create an indication under an asset with optional phase, milestone, milestone date, peak sales ($M), and lead flag. | | update_biopharma_indication | Update a biopharma indication by UUID. Nullable fields can be cleared with null. |

Email Templates

| Tool | Description | |------|-------------| | list_email_templates | List live (non-archived, latest-version) templates for the team. Optional folder filter. | | get_email_template | Fetch one template; pass include_history=true to also return the version chain. | | create_email_template | Create a template (subject + body, with whitelisted handlebars like {{first_name}}, {{company_name}}). | | update_email_template | Patch a template — creates a new version row; prior version stays in the history chain. |

Email Outreach (formerly Email Campaigns)

| Tool | Description | |------|-------------| | list_email_outreach | List the team's outreach sends (newest first). Filters: project_id, status, limit. | | get_email_outreach | Fetch an outreach with its per-recipient rows (each row carries its own uuid for per-row schedule overrides). | | create_email_outreach | Atomic create: outreach row + recipient rows + Cloud Run draft trigger, all-or-nothing. Supports fresh (recipients list, optional project_id to attach to a deal) or follow-up (follow_up spec with same_thread/new_thread). group_by picks one email per company (default) or one per person — use person for a People List tracker roster, and for anyone with no company. | | add_email_outreach_recipients | Add companies/people to an existing outreach with its own template; drafts only the new emails. Idempotent per request_id. | | update_email_outreach_emails | unschedule specific emails back to drafts, or cancel them for good (never sent, provider draft deleted). | | schedule_email_outreach | Schedule sends via Cloud Tasks. Single base time + optional stagger (interval_minutes_between, emails_per_interval for batches like 50 every 5 min), OR per-row schedules override list. |

Delete

| Tool | Description | |------|-------------| | delete_record | Delete any record by type and UUID. Supports: company, person, task, metric_schema, project, comment, status_definition, email, calendar, file, port_co_relationship, fund, email_template, biopharma_asset, biopharma_indication, email_campaign, workflow. workflow removes a tracker from a project (cascades its views + tracked companies/people; tasks keep their rows with workflow_id cleared). For company, this is team-scoped — it removes the company from your team only (the company record and other teams' data are preserved); re-adding it restores your team's records. |

Prospecting-only

These tools are surfaced only to prospecting-only tenants (accounts with the prospecting_only flag). Such accounts see these plus the three Comments tools and nothing else. Fit ratings are 1–5 where 1 = most attractive.

| Tool | Description | |------|-------------| | get_public_prospect_schema | List every public-prospect column (~100: key, type, unit, group, description, supported filter ops, sortable) plus the research interpretations behind the EDGAR columns. Call before building filters / return_columns. | | query_public_company_prospects | Search public-company prospects with named filters (GICS, priority, in_crm, Fit ratings, financials, opportunity size, debt, tag) plus generic filters on any column and return_columns; sort + pagination. Returns a canonical internal URL, AI-enriched firmographics, headline financials, a debt summary, the five Fit ratings, and the prospecting layer. | | get_public_prospect | One public prospect with every column and its canonical internal URL; opt-in include of research, debt_facilities, syndicate. Includes import_cn_hk_tw_pct and import_concentration when available. Also accepts include: ["suppliers"] for trade and contact/address evidence; paginate with supplier_offset/supplier_limit and observation_offset/observation_limit (default 20, max 200). | | get_portfolio_prospect_schema | List every portfolio-prospect column (sponsor, prospecting layer, Fit, GICS, firmographics) with types and supported filter ops. | | query_portfolio_company_prospects | Search PE/VC portfolio-company prospects (by sponsor, stake, GICS, Fit, revenue, employees, tag) plus generic filters on any column and return_columns. Returns a canonical internal URL, portfolio context + firmographics + Fit + prospecting layer. | | get_portfolio_prospect | One portfolio prospect with every column and its canonical internal URL; opt-in include of research. Includes import_cn_hk_tw_pct and import_concentration when available. Also accepts include: ["suppliers"] for trade and contact/address evidence; paginate with supplier_offset/supplier_limit and observation_offset/observation_limit (default 20, max 200). | | list_trackers | List the team's Pipeline trackers (id, canonical internal URL, name, owner, company count, default flag). | | get_tracker | Get a tracker with its canonical internal URL + a page of its companies (hydrated with prospect data) and the tracker's comment thread. Trip trackers also return trip_suggestions (ranked prospects + job status). | | update_prospect | Update a prospect's priority, referral, opportunity_size, tags, and manual Fit-rating overrides (by prospect_type + uuid). | | promote_prospects | Add prospects to a tracker (async promotion into the pipeline); omit tracker_id for the default tracker. | | create_tracker | Create a new Pipeline tracker. Pass location to make it a trip tracker (auto-generates metro-ranked prospect suggestions). | | update_tracker | Rename / re-describe / re-anchor (location) a tracker (the default tracker is immutable). | | find_comparable_prospects | Start (or attach to) an async AI job that finds comparable prospects for a target Pipeline company or public / portfolio prospect, searching only the team's prospect lists. Requires PROSPECT_COMPS_ENABLED on the deployment. | | get_comparable_prospects | Latest comparable-prospect run for a target (prospects with canonical internal URLs, financials, Fit, score, confidence, reasons, evidence, caveats) plus the live job status; run is null until one has been generated. | | find_trip_prospects | Start (or attach to) a job that regenerates a trip tracker's prospect suggestions: the tracker's anchor location is expanded into its metro and the team's public / portfolio prospects headquartered there are ranked by Fit, priority, opportunity size and timing. Read the list via get_tracker (trip_suggestions). Requires PROSPECT_TRIP_PLANNER_ENABLED on the deployment. |

Configuration

| Environment Variable | Required | Default | Description | |---------------------|----------|---------|-------------| | DEBREU_API_KEY | Yes | — | Your Debreu API key | | DEBREU_API_URL | No | derived from key | API base URL (override for self-hosted or dev) | | MCP_PUBLIC_URL | No | derived (mcp.<host>/mcp) | Hosted/OAuth only: this server's canonical URL, advertised in OAuth Protected Resource Metadata. | | OAUTH_ISSUER_URL | No | derived (auth.<host>) | Hosted/OAuth only: the OAuth authorization server (issuer) for remote "Connect". |

The API host is derived from your key automatically: keys that embed a workspace identifier route to that workspace's API; all other keys route to https://api.debreu.ai. You never need to set DEBREU_API_URL for normal use.

API Key Management

Manage your API keys from Account Settings (click your avatar in the top-right). You can create new keys, view existing ones, and revoke any key from there.

Data Scoping

All data is scoped to your user and team. You will only see companies, people, and data that your team has access to in Debreu. Creating records through the API links them to your account automatically.

Company-name lookups use exact names and aliases. Similar names are returned as candidates for review, never selected automatically.

As of 2.159.0, candidates without a visible, deliverable contact omit approve and return approval_blocker. summary.company_approvals counts eligible companies; summary.contact_blocked counts unavailable candidates. Update the company’s contacts in the CRM and reread the run to refresh eligibility. Agent 409 errors distinguish unfinished conversations, paused/ended runs, stale revisions, and concurrent work, with safe recovery instructions.