Multipliers Third-Party Agent Integration

Build agents that your customers can install, govern, and measure alongside their first-party Multipliers fleet.

This is the canonical public reference for any team building an agent that needs to operate inside a customer's Multipliers tenant — whether you ship an MCP server, an A2A-compliant agent host, a Salesforce Apex Invocable, a Slack bot, or an internal microservice that just wants its value to show up on the customer's governance dashboard.

Every endpoint URL, JSON schema, and curl example below is anchored to a shipped, deployed route at code SHA bdbbb5e. Sections labeled "Roadmap" in §8 are explicitly NOT shipped yet; everything else works today.

Why integrate with Multipliers

Three reasons your team should care:

1. Your value becomes measurable in the customer's terms. Every customer running Multipliers has a governance dashboard that aggregates dollars saved, hours returned, risk avoided, and audit artifacts produced — across their first-party Multipliers agents AND every third-party agent they've connected. Your agent's contribution surfaces there with the same denomination. That dashboard is what your buyer takes to their CFO. Being on it = a sales asset.
2. Customers wire you to their existing business processes — without per-client code. Tenant admins map your agent to their value chain (Salesforce / ServiceNow / SAP / Shopify / SFCC / commercetools / NetSuite and the rest of the 75-platform connector catalog) through the admin UI. No custom branches, no per-client builds, no deploys for you.
3. You stay substrate-agnostic. Multipliers runs on Bedrock, Vertex, Foundry, or direct-lab tenants — your integration code is identical across all of them. No model-lab lock-in for your ecosystem.

Who this is for — pick your scenario

Different builders start at different points. Find your row, jump to the section that matches. Each scenario section is self-contained — you do not have to read this doc front-to-back.

1. The 5-contract architecture (concept overview)

Multipliers treats every agent — first-party catalog agent, partner agent, customer in-house agent, third-party MCP server — as a single typed object satisfying up to five runtime contracts:

1. MCP toolSchema — what tools the agent exposes (JSON Schema per tool).
2. A2A AgentCard — discoverability + capability declaration in the converging A2A protocol.
3. MVE outcomes — value the agent declares it produced per run, in the Multipliers Value Envelope v1 vocabulary.
4. valueChainBindings — which industry processes / stages / metrics the agent contributes to.
5. groundingBindings — which tenant-Brain context the agent must consult before acting (entities · policies · prior runs).

The full TypeScript interface is in this repository at packages/agents/src/runtime/AgentRuntimeContract.ts (lines 128–145 for the top-level shape).

What you have to satisfy depends on your integration shape:

The §8 roadmap describes the path to give external agents full 6-contract governance parity with first-party catalog agents through the typed POST /api/v1/agents/external registration endpoint.

2. MVE-via-MCP — emit value envelopes from your MCP server

This is the most common integration shape today. If you've built an MCP server and your tools produce value, this is your path.

2.1 What MVE is

The Multipliers Value Envelope (MVE) v1 is a small, additive JSON field on your MCP tool result. It declares the business value your tool just produced — dollars, hours, count of recommendations, compliance events, whatever fits the 15-kind controlled vocabulary (§2.5).

The authoritative JSON Schema lives at:

https://multipliers.ai/value-envelope/v1/schema.json

It is dependency-free, additive (does not change your existing tool output shape), and ignored by clients who don't understand it.

2.2 Quickstart

Fetch the schema and the kinds list:

curl https://multipliers.ai/value-envelope/v1/schema.json
curl https://multipliers.ai/value-envelope/v1/kinds

The minimal envelope looks like this — your tool's normal result payload, plus a _meta.multipliers_value field:

{
  "result": {
    "content": [{ "type": "text", "text": "Categorized 47 tickets." }]
  },
  "_meta": {
    "multipliers_value": {
      "kind": "analyst_hours_saved",
      "amountHours": 2.5,
      "confidence": "estimated",
      "description": "Auto-categorized 47 tickets via fuzzy match"
    }
  }
}

2.3 TypeScript SDK

We publish a tiny, dependency-free helper at @multipliers/value-envelope:

import { attachMVE } from '@multipliers/value-envelope';

const result = await myTool(input);
return attachMVE(result, {
  kind: 'analyst_hours_saved',
  amountHours: 2.5,
  confidence: 'estimated',
  description: 'Auto-categorized 47 tickets via fuzzy match',
});

The package validates outcomes at attach time so shape errors surface in your dev loop, not in production logs.

Reference implementations exist for Python and Go in the monorepo under packages/value-envelope/refimpl/. They are dependency-free and copy-friendly — drop the file into your project if a package install is awkward.

2.4 How customers see your value

Once a customer connects your MCP server to their tenant (admin UI under /admin/ecosystem), every _meta.multipliers_value you emit is captured into their agent_run_outcomes table with source='mcp_external'. From that point on, your agent shows up in:

• /governance/summary — headline dollars / hours / risk avoided rollup. Your contribution is summed alongside theirs.
• /governance/by-source — first-party vs mcp_external vs external_api split. The tenant admin can see how much of their ROI is coming from third-party agents (you).
• /governance/agents-inventory — per-agent classification: emitting (good — value flowing) · silent (responds but never emits MVE) · dormant (no calls in the window) · non_conformant (emits MVE that fails validation).

The classification is the customer's lens on whether your agent is pulling its weight. If your agent is consistently silent, the customer's Forward Deployed Engineer (or you) will be asked to wire MVE.

2.5 The 15-kind controlled vocabulary

The vocabulary is deliberately small and stable. Adding a new kind is a v1.x evolution we coordinate publicly.

Source of truth: packages/value-envelope/src/index.ts exports VALUE_KINDS and apps/api/src/routes/value-envelope.ts serves the JSON Schema. Both are kept in lockstep.

3. Direct outcome POST — non-MCP agents

New in 2026-05-28 (Tier B closure).

For agents that can't speak MCP — a Salesforce Apex Invocable, a Slack bot, a ServiceNow Action, an internal microservice — POST /api/v1/outcomes accepts the same outcome shape over plain HTTP.

3.1 Endpoint

POST /api/v1/outcomes
Host: multipliers.ai
Authorization: Bearer mt_<64 hex chars>
Idempotency-Key: <client-generated unique string, 1..255 chars>
Content-Type: application/json

The /api/v1/* namespace is the public-versioned surface for third-party agent authors. Additive field changes ship under v1; any breaking shape change cuts v2.

3.2 Request body

{
  "kind": "analyst_hours_saved",
  "amountHours": 2.5,
  "confidence": "estimated",
  "description": "Auto-routed 14 tier-1 tickets to the right queue",
  "runId": "11111111-1111-1111-1111-111111111111",
  "templateId": "acme-pricing-optimizer",
  "linkedResourceKind": "salesforce_opportunity",
  "linkedResourceId": "006xxx0000000000",
  "metadata": { "queue": "support-tier-1", "model": "haiku" }
}

Field rules:

• kind — required; one of the 15 vocabulary kinds in §2.5.
• confidence — required; one of measured | estimated | projected.
• description — required; 4–500 characters; not logged into audit metadata for PII discipline (see §3.5).
• amountUsd / amountCount / amountHours — at least one recommended; all are optional but the outcome is most useful when at least one is present.
• runId — optional; when present must reference an agent_runs row in this tenant (cross-tenant probes silently return 404).
• templateId — optional; defaults to external_api if omitted.
• linkedResourceKind + linkedResourceId — optional; use to tie the outcome to a customer-side record (an opportunity, a ticket).
• metadata — optional; any JSON object. PII-clean please — the customer's compliance team reads this.

Note: tenantId is intentionally absent from the request body. It comes from the bearer token; cross-tenant body fields cannot exist by construction.

3.3 Response

202 Accepted:

{
  "outcomeId": "22222222-2222-2222-2222-222222222222",
  "idempotentReplay": false,
  "source": "external_api"
}

Other status codes:

3.4 Idempotency

Idempotency-Key is required. Behavior:

• Same key + same body → returns the same outcomeId with idempotentReplay: true. Safe to retry on network failures.
• Same key + DIFFERENT body → 409 idempotency_key_conflict. Use a fresh key for a new outcome.
• Same key, previous attempt failed → next attempt with same key + same body re-executes (failures don't poison the key forever).

Recommended: derive the key from your side (e.g. outcome:<your-run-id>) so retries are deterministic.

3.5 PII discipline

The description text and the metadata blob are persisted into agent_run_outcomes (where the customer's governance dashboards read from). They are never persisted into audit_events, which carries only IDs + kind + amounts. This means the security team can audit "who emitted what value when" without seeing the operational text.

Keep description operator-facing and PII-free.

3.6 Rate limit

100 requests per minute per token. The limiter is keyed on tokenId (not IP) — one tenant's integration can't starve another tenant's. Overflow returns 429 rate_limit_exceeded with retryAfter: 60 in the body.

3.7 Auth — getting a tenant API token

The customer's tenant admin issues your token through their admin surface. The underlying admin route is:

POST /api/admin/tenants/{tenantId}/api-tokens
Authorization: Bearer <admin-firebase-jwt>
Content-Type: application/json

{
  "name": "Acme Pricing Optimizer (prod)",
  "scope": "outcomes:write",
  "ttlDays": 365
}

Response (the plaintext token is shown once, then sha256-hashed server-side):

{
  "token": "mt_<64 hex chars>",
  "tokenId": "33333333-3333-3333-3333-333333333333",
  "scope": "outcomes:write",
  "createdAt": "2026-05-28T12:00:00Z",
  "expiresAt": "2027-05-28T12:00:00Z",
  "_warning": "This token is shown ONLY ONCE. Save it now — it cannot be retrieved later."
}

Token format: mt_ prefix + 64 hex characters. Scope strings are checked in middleware before the route handler runs.

4. A2A external-agent registration

For external A2A-compliant agent hosts — including customer GSI builds, partner platforms, and customer in-house agents — that want to be discoverable + invocable from inside a tenant.

4.1 Register your agent

POST /a2a/agents
Host: multipliers.ai
Authorization: Bearer <tenant-admin-firebase-jwt>
Content-Type: application/json

Body:

{
  "agentCard": {
    "id": "acme-pricing-optimizer",
    "name": "Acme Pricing Optimizer",
    "description": "Reviews weekly competitor pricing and flags margin compression",
    "url": "https://agents.acme.example/pricing-optimizer/.well-known/agent.json",
    "version": "1.2.0",
    "capabilities": { "streaming": false, "pushNotifications": false },
    "authentication": { "schemes": ["bearer"] },
    "defaultInputModes": ["application/json"],
    "defaultOutputModes": ["application/json"],
    "skills": [
      {
        "id": "review-pricing",
        "name": "Review weekly pricing",
        "description": "Pull competitor prices and flag SKUs at risk"
      }
    ]
  },
  "baseUrl": "https://agents.acme.example/pricing-optimizer",
  "authToken": "<your-bearer-token-stored-encrypted-in-the-tenant-vault>"
}

Notes:

• baseUrl must be HTTPS in production (HTTP rejected with 400).
• authToken is optional; when present it is stored in the customer tenant's encrypted secret vault under scope='platform:a2a', key='a2a:external:<agentId>:bearer'. The raw value never lives in the external_a2a_agents table.
• Re-registering the same agentId for the same tenant updates the existing row (idempotent on (tenantId, agentId)).

4.2 Heartbeat

Tell us your agent is alive so the customer's UI shows it as online:

POST /a2a/agents/{id}/heartbeat
Authorization: Bearer <tenant-admin-firebase-jwt>

Updates last_seen_at and optionally status (available | offline | custom). No body required.

4.3 List registered external agents

GET /a2a/agents/external
Authorization: Bearer <tenant-jwt>

Returns this tenant's registered external A2A agents (the customer's admins can see what's been wired into their tenant).

4.4 Revoke

DELETE /a2a/agents/{id}
Authorization: Bearer <tenant-admin-firebase-jwt>

Soft-delete; preserves the audit trail.

4.5 Discovery

After registration, the customer's tenant exposes:

• GET /.well-known/agent.json — cards index (lists all agents in this tenant's catalog, including yours).
• GET /.well-known/agents/{templateId}.json — per-agent detail.
• GET /.well-known/a2a-agent.json — the A2A protocol agent-card view (separate URL from the cards index — see §5.1).

5. Public discovery + OpenAPI

5.1 /.well-known endpoints (no auth required)

These URLs are stable, cacheable, and form the public discovery surface.

A note on the /agent.json vs /a2a-agent.json split: the former is the cards INDEX (the canonical surface for ecosystem integrators discovering what's available); the latter is the A2A PROTOCOL shape (what A2A-spec clients expect). The cards-index response carries an a2aProtocolAgentCardUrl pointer so A2A clients can follow it.

5.2 Integration discovery JSON

New in 2026-05-28. A single URL that returns every integration surface, its auth mechanism, and the schemas you need — so your client never has to read prose docs to find the URLs.

curl https://multipliers.ai/.well-known/multipliers-agent-integration.json

Response (abridged):

{
  "version": "1",
  "name": "Multipliers AI Platform",
  "platformUrl": "https://multipliers.ai",
  "docsUrl": "https://multipliers.ai/docs/third-party-agent-integration",
  "endpoints": {
    "wellKnownAgentCard": "https://multipliers.ai/.well-known/agent.json",
    "wellKnownA2aAgentCard": "https://multipliers.ai/.well-known/a2a-agent.json",
    "tenantDiscovery": "https://multipliers.ai/api/v1/tenant/me",
    "outcomesPost": "https://multipliers.ai/api/v1/outcomes",
    "a2aAgentRegistration": "https://multipliers.ai/a2a/agents",
    "a2aTasksRpc": "https://multipliers.ai/a2a/tasks",
    "mcpRpc": "https://multipliers.ai/api/mcp/rpc",
    "mcpAdminCatalog": "https://multipliers.ai/api/mcp-admin/catalog",
    "openApiSpec": "https://multipliers.ai/api/openapi.yaml",
    "openApiUi": "https://multipliers.ai/api/docs"
  },
  "schemas": {
    "mveEnvelope": "https://multipliers.ai/value-envelope/v1/schema.json",
    "mveKinds": "https://multipliers.ai/value-envelope/v1/kinds",
    "agentRuntimeContract": "https://multipliers.ai/.well-known/agent-runtime-contract.schema.json"
  },
  "authentication": {
    "tenantApiToken": {
      "scheme": "Bearer",
      "tokenFormat": "mt_<64 hex chars>",
      "scopes": ["outcomes:write", "embedded_ui"],
      "issuanceEndpoint": "POST /api/admin/tenants/{tenantId}/api-tokens"
    },
    "mcpBearer": {
      "scheme": "Bearer",
      "tokenFormat": "OAuth 2.0 access token",
      "scopes": ["mcp.invoke", "mcp.discover"],
      "issuanceEndpoint": "POST /oauth/token"
    }
  },
  "scenarios": [
    { "id": "mcp-author", "primaryEndpoint": "mveEnvelope" },
    { "id": "non-mcp-author", "primaryEndpoint": "outcomesPost" },
    { "id": "a2a-host", "primaryEndpoint": "a2aAgentRegistration" },
    { "id": "ecosystem-integrator", "primaryEndpoint": "openApiUi" }
  ]
}

Versioning: adding fields is non-breaking within v1. Removing or renaming a field requires v2 shipped at the same URL.

Cache: public, max-age=3600.

5.3 OpenAPI

GET /api/openapi.yaml
GET /api/openapi.json
GET /api/docs              (Redoc UI)

The spec is at docs/api/openapi.yaml in the monorepo. Today the spec is partial — it covers the highest-value third-party-facing surfaces (the ones documented in this spec) and a handful of operational endpoints. Most of the ~650 internal routes are not yet covered. The §8 roadmap describes the uplift to full coverage.

6. Tenant API tokens — canonical auth for non-user surfaces

mt_* tenant API tokens are the auth mechanism for every public surface a third party calls without a logged-in user (your CI, your backend, your scheduled job). They are issued by tenant admins, scoped to a capability, optionally bound to a specific agent, and have a TTL.

6.1 Format

mt_<64 hex chars>

The prefix is a load-bearing namespace — never use it for anything else. The plaintext is shown once on issuance, then SHA-256 hashed server-side. There is no recovery path; rotated tokens are re-issued, not retrieved.

6.2 Scopes

Scopes are additive: a single token can carry one scope today (free-form text validated as ≤ 255 chars). The middleware does prefix-match checks (outcomes:write matches the literal scope).

6.3 Optional agent-binding

When issued with agentId: "<template-id>", the token is restricted to acting on behalf of that specific agent. The route handler can check req.tokenAuth.agentId against the request's claimed agent and reject mismatches. Use this when issuing tokens for embedded agent UIs.

6.4 Lifecycle

• Issue: POST /api/admin/tenants/{tenantId}/api-tokens (admin role required; cross-tenant issuance blocked at the route).
• List: GET /api/admin/tenants/{tenantId}/api-tokens (returns metadata only — never plaintext).
• Revoke: DELETE /api/admin/tenants/{tenantId}/api-tokens/{id} (soft-delete; preserves audit trail).
• Rotate: revoke + issue. There is no in-place rotation today.

6.5 Bearer-to-tenant discovery

New in 2026-05-28. Hand a third party an mt_* token and they have no way to know which tenant it's bound to without an out-of-band channel. This endpoint solves it:

curl https://multipliers.ai/api/v1/tenant/me \
  -H "Authorization: Bearer mt_<64 hex>"

Response:

{
  "tenantId": "44444444-4444-4444-4444-444444444444",
  "displayName": "Acme Corp",
  "tokenScope": "outcomes:write",
  "tokenName": "Acme Pricing Optimizer (prod)",
  "boundAgentId": null,
  "apiBaseUrl": "https://multipliers.ai/api/v1",
  "docsUrl": "https://multipliers.ai/docs/third-party-agent-integration"
}

Cache: private, max-age=300 (per-tenant; CDN-untouchable).

7. Governance — your agent in the customer's dashboard

What the customer's tenant admin sees once your integration is live.

7.1 Top-line surfaces

• /governance/summary — headline dollars / hours / risk avoided / artifacts produced rollup. Aggregate across all agents in the tenant including yours.
• /governance/by-source — split by source: multipliers (first-party catalog), mcp_external (third-party MCP), or external_api (you, via §3 direct POST). The tenant admin can see exactly how much of their ROI is coming from each source.
• /governance/agents-inventory — per-agent inventory with classification per agent.

7.2 Agent classification

Your reputation depends on emitting MVE. Silent agents are flagged. If you can't reasonably attach a value envelope to a tool call, emit a tool_invocation outcome with amountCount: 1 so the dashboard at minimum shows volume. The MVE-via-MCP capture path does this automatically when an MCP tool returns no envelope; for §3 direct POST you have to do it yourself.

7.3 Cross-tenant isolation

Every outcome, run, audit row, and configuration object in Multipliers carries tenant_id. Routes enforce tenant_id FIRST in every WHERE clause. The bearer token determines tenantId — the request body cannot override it. Cross-tenant probes (e.g. naming another tenant's runId) return 404 to avoid leaking existence.

This is the platform-wide invariant; your integration inherits it automatically.

8. Roadmap — what's coming (Tier C)

Explicitly NOT shipped yet. The items below are on the near-to-medium roadmap. We will not surface fake endpoints — when each ships, it lands at the URL listed and this section is amended.

Dates are estimates, not commitments. If something on this list is load-bearing for your roadmap, talk to us — order of operations sometimes shuffles based on design-partner pull.

9. Known limitations

We'd rather flag these upfront than have you find them at integration time.

9.1 Auth fragmentation

Five mechanisms exist across the platform today:

1. Firebase JWT (logged-in users)
2. mt_* tenant API tokens (this spec's canonical path for third parties)
3. mp_* platform keys (legacy; deprecation path TBD)
4. Custom OAuth Bearer per-MCP-server (per-tenant vault credentials)
5. Vault credentials for embedded surface auth

The §8 roadmap consolidates non-user-surface auth to mt_*. Until then, follow each section's specific guidance.

9.2 OpenAPI partial coverage

The openapi.yaml covers the surfaces documented in this spec plus a handful of operational endpoints — roughly 1–2% of the route surface today. The §8 roadmap brings full coverage.

If you need a route documented sooner because it blocks your integration, open a GitHub Discussion (§11) — coverage requests get prioritized.

9.3 No @multipliers/agent-sdk yet

@multipliers/value-envelope is the only published SDK today (covers the MVE envelope authoring path). The broader agent SDK (typed outcomes POST · spec-card authoring · external-agent registration) ships in Q3 2026 (§8). Until then, hand-rolled HTTP against the endpoints in §3, §4, and §6.5 works fine — the URLs and shapes documented here are stable within v1.

9.4 No inbound run-creation webhook

External agents can emit outcomes via §3 POST /api/v1/outcomes but cannot declare a full agent_runs record from outside today. The §8 roadmap ships POST /webhooks/v1/agent-run for HMAC-signed external run declarations — useful when your agent runs entirely off-platform and you want a synthetic run record + outcomes captured in one shot.

10. Getting started — your first integration

A concrete 5-step quickstart from zero to "the customer sees your first outcome on their dashboard."

Step 1: Pick your shape

Re-read §2 / §3 / §4 to pick the integration shape that fits your codebase. Most teams start with §3 (direct outcome POST) because it requires the least scaffolding — just an HTTP POST from wherever you already run.

Step 2: Ask the customer to issue a tenant API token

Direct the tenant admin to their /settings/api-keys page and have them issue a token with scope: outcomes:write. The plaintext shows once — they need to copy it to you securely (your encrypted vault, 1Password, etc.) before they navigate away.

Step 3: Verify the token and discover tenant context

curl https://multipliers.ai/api/v1/tenant/me \
  -H "Authorization: Bearer mt_<your-token>"

You should see the tenant's tenantId, displayName, and your tokenScope. If you get 401, the token is invalid or revoked.

Step 4: Emit your first outcome

curl -X POST https://multipliers.ai/api/v1/outcomes \
  -H "Authorization: Bearer mt_<your-token>" \
  -H "Idempotency-Key: my-first-outcome-001" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "analyst_hours_saved",
    "amountHours": 0.5,
    "confidence": "estimated",
    "description": "First test outcome from my integration"
  }'

You should get back 202 with an outcomeId. Re-run the same command — you should see idempotentReplay: true with the same outcomeId (idempotency working).

Step 5: Verify in the customer's governance dashboard

Have the tenant admin visit /governance/agents-inventory — your source='external_api' row should appear with classification emitting. Visit /governance/summary — your 0.5 hours should be included in the headline rollup.

You're integrated.

11. Support + contact

• Email: agents@multipliers.ai (general integration questions)
• Security: security@multipliers.ai (per /.well-known/security.txt)
• GitHub Discussions: github.com/multipliers-ai/platform/discussions (open / public; integration support + roadmap input)
• Slack community: invite link published on multipliers.ai/community (developer-to-developer chat)

For enterprise integrations (custom GSI builds, large partner deployments, integrations gated on a paid tier), the Forward Deployed Engineering engagement model applies. Reach out via the email above and we'll route you to an FDE for scoping.

Appendix A — Schemas + reference links

• MVE envelope JSON Schema: https://multipliers.ai/value-envelope/v1/schema.json
• MVE controlled vocabulary: https://multipliers.ai/value-envelope/v1/kinds
• Integration discovery JSON: https://multipliers.ai/.well-known/multipliers-agent-integration.json
• A2A protocol agent card (this tenant): https://multipliers.ai/.well-known/a2a-agent.json
• Agent cards index (this tenant): https://multipliers.ai/.well-known/agent.json
• OpenAPI spec: https://multipliers.ai/api/openapi.yaml
• Redoc UI: https://multipliers.ai/api/docs
• AgentRuntimeContract (TypeScript source): packages/agents/src/runtime/AgentRuntimeContract.ts in this monorepo (lines 128–145 for the top-level shape)
• A2A protocol spec: agentprotocol.dev (external — the converging A2A standard we implement)

Appendix B — Status and verification anchor

• Spec version: 1.0
• Authored: 2026-05-28
• Verified against shipped code at: SHA bdbbb5e (Tier B third-party integration wiring merge)
• Endpoints in §2 / §3 / §4 / §5 / §6: all verified shipped
• Capabilities in §8: explicitly labeled Roadmap — not shipped
• Maintainer: Multipliers AI Platform team; updates land in this repository under docs/specs/

Next planned revision: post-Tier-C closure (when POST /api/v1/agents/external and the @multipliers/agent-sdk package ship). At that point §8 entries flip into the main body and a new §8 roadmap is curated.