# io.usefulapi/mercoa (remote · mercoa.usefulapi.io)

Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.

- Trust score: 71/100 (medium)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `mercoa.usefulapi.io`: 71/100 (this document), [markdown](https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa.md), [page](https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa)

## Channel facts

- Endpoint: `https://mercoa.usefulapi.io/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `1.0.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 78/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation is enforced on tool calls, advertised via RFC 9728 protected-resource metadata. Discovery is public, which costs nothing: no tool can be invoked without a token.
  - HTTPS not yet verified: we couldn't determine whether a plaintext access path exists.
  - HSTS check failed: the Strict-Transport-Security header is absent.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
  - The authorisation server offers only Dynamic Client Registration (RFC 7591), which MCP 2026-07-28 deprecated in favour of Client ID Metadata Documents.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 66/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 2638 tokens (~155/item across 17 items; 17 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 60/100
  - Spec-recency check failed: implements MCP spec 2025-06-18; the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http io-usefulapi-mercoa https://mercoa.usefulapi.io/mcp
```

### Codex

```toml
[mcp_servers.io-usefulapi-mercoa]
url = "https://mercoa.usefulapi.io/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "io-usefulapi-mercoa": {
      "type": "remote",
      "url": "https://mercoa.usefulapi.io/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add io-usefulapi-mercoa --url https://mercoa.usefulapi.io/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  io-usefulapi-mercoa:
    url: "https://mercoa.usefulapi.io/mcp"
```

### Other

```json
{
  "mcpServers": {
    "io-usefulapi-mercoa": {
      "type": "http",
      "url": "https://mercoa.usefulapi.io/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 71, +1)

No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-08-02 (score 70, +42)

- [security improvement] Authorization: unverified → pass
- [functional regression] MCP protocol: unverified → fail
- [functional improvement] Endpoint reachability: not serving MCP → reachable
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Stability: unverified → 0.20

### 2026-08-01 (score 28, −42)

- [security regression] Endpoint reachability: reachable → not serving MCP
- [security regression] Stability: 0.13 → unverified
- [security regression] Authorization: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Capabilities: fail → unverified

### 2026-07-31 (score 70, +4)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 66, −2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 67, 0)

- [functional improvement] Stability: unverified → 0.03

### 2026-07-27 (score 67, +55)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

## MCP tools (17)

### `mercoa_find_entities` (~213 tokens)

Find entities

Find/search entities (buyers, vendors, payors, payees). Use to look up counterparties by name/email/foreignId or list all. GET /entity.

Input parameters:

- `foreignId`: Your system's ID(s) for the entity.
- `isCustomer` (boolean): If true, only entities with a direct relationship to your organization.
- `isPayee` (boolean): Filter entities marked as payees.
- `isPayor` (boolean): Filter entities marked as payors.
- `limit` (integer): Max entities to return (1-100, default 10).
- `paymentMethods` (boolean): If true, include payment methods in the response.
- `returnMetadata`: Metadata key(s) to include in the response.
- `search` (string): Search by name, email, emailTo, entity ID, or foreign ID (partial matches).
- `startingAfter` (string): Entity ID cursor for pagination.
- `status`: Entity status filter (e.g. verified, pending).

### `mercoa_get_entity` (~48 tokens)

Get entity

Get a single entity by ID (or foreign ID). GET /entity/{entityId}.

Input parameters:

- `entityId` (string, required): Entity ID (e.g. ent_...) or foreign ID.

### `mercoa_get_entity_events` (~103 tokens)

Get entity events

Get the event/audit log for an entity. GET /entity/{entityId}/events.

Input parameters:

- `endDate` (string): End date filter (ISO 8601).
- `entityId` (string, required): Entity ID or foreign ID.
- `limit` (integer): Max events to return (1-100).
- `startDate` (string): Start date filter (ISO 8601).
- `startingAfter` (string): Event ID cursor for pagination.

### `mercoa_get_entity_invoice_metrics` (~331 tokens)

Get entity invoice metrics

Get aggregate invoice metrics (totals/counts, grouped by currency) for an entity's payables/receivables — for AP/AR dashboards and aging. GET /entity/{entityId}/invoice-metrics.

Input parameters:

- `approverId`: Filter by assigned approver user ID(s).
- `currency`: Currency code(s) to filter on, e.g. USD.
- `dateType` (string): Date type to filter by (e.g. CREATED_AT, DUE_DATE).
- `endDate` (string): End date filter (ISO 8601).
- `entityId` (string, required): Entity ID or foreign ID.
- `excludePayables` (boolean): Only return receivables (exclude payables).
- `excludeReceivables` (boolean): Only return payables (exclude receivables).
- `groupBy`: Additional grouping (e.g. by status).
- `invoiceId`: Filter by invoice ID(s) or foreign ID(s).
- `payerId`: Filter by payer ID(s).
- `returnByDate` (string): Group metrics by date, e.g. CREATION_DATE or DUE_DATE.
- `returnByDateFrequency` (string): Frequency for date grouping (e.g. DAILY, MONTHLY).
- `search` (string): Search by vendor name, invoice number, check number, or amount.
- `startDate` (string): Start date filter (ISO 8601).
- `status`: Invoice status filter (e.g. NEW, SCHEDULED, PAID).
- `vendorId`: Filter by vendor ID(s).

### `mercoa_list_entity_payment_methods` (~73 tokens)

List entity payment methods

List an entity's payment methods (bank accounts, cards, check, etc.). GET /entity/{entityId}/paymentMethods.

Input parameters:

- `entityId` (string, required): Entity ID or foreign ID.
- `type` (string): Filter by payment method type (e.g. bankAccount, card, check).

### `mercoa_get_payment_method` (~66 tokens)

Get payment method

Get a single payment method for an entity. GET /entity/{entityId}/paymentMethod/{paymentMethodId}.

Input parameters:

- `entityId` (string, required): Entity ID or foreign ID.
- `paymentMethodId` (string, required): Payment method ID (e.g. pm_...).

### `mercoa_list_entity_users` (~48 tokens)

List entity users

List the users belonging to an entity (approvers, admins, etc.). GET /entity/{entityId}/users.

Input parameters:

- `entityId` (string, required): Entity ID or foreign ID.

### `mercoa_find_invoices` (~429 tokens)

Find invoices

Find/search invoices (bills) across payers and vendors. Filter by status, entity, date, approver and more. GET /invoices (plural list endpoint).

Input parameters:

- `approverAction`: Filter by approver action (use with approverId), e.g. APPROVE.
- `approverId`: Filter by assigned approver user ID(s).
- `creatorUserId`: Filter by the user ID(s) that created the invoice.
- `dateType` (string): Date type to filter by (e.g. CREATED_AT, DUE_DATE).
- `endDate` (string): End date filter (ISO 8601).
- `entityGroupId` (string): Filter by entity group ID.
- `entityId`: Filter by entity (payer or vendor) ID(s) or foreign ID(s).
- `invoiceId`: Filter by invoice ID(s) or foreign ID(s).
- `invoiceTemplateId`: Filter by invoice template ID(s).
- `limit` (integer): Max invoices to return (1-100, default 10).
- `orderBy` (string): Field to order by (e.g. CREATED_AT, AMOUNT, DUE_DATE).
- `orderDirection` (string): asc or desc.
- `payerId`: Filter by payer ID(s) or foreign ID(s).
- `paymentType`: Filter by payment type (e.g. recurring).
- `returnPayerMetadata` (boolean): Include payer metadata in the response.
- `returnPaymentTiming` (boolean): Include payment timing in the response.
- `returnVendorMetadata` (boolean): Include vendor metadata in the response.
- `search` (string): Search by vendor name, invoice number, check number, or amount.
- `startDate` (string): Start date filter (ISO 8601).
- `startingAfter` (string): Invoice ID cursor for pagination.
- `status`: Invoice status filter (e.g. DRAFT, NEW, APPROVED, SCHEDULED, PAID).
- `vendorId`: Filter by vendor ID(s) or foreign ID(s).

### `mercoa_get_invoice` (~47 tokens)

Get invoice

Get a single invoice (bill) by ID. GET /invoice/{invoiceId}.

Input parameters:

- `invoiceId` (string, required): Invoice ID (e.g. in_...) or foreign ID.

### `mercoa_get_invoice_events` (~110 tokens)

Get invoice events

Get the event/audit log for an invoice (status changes, approvals, payments). GET /invoice/{invoiceId}/events.

Input parameters:

- `endDate` (string): End date filter (ISO 8601).
- `invoiceId` (string, required): Invoice ID or foreign ID.
- `limit` (integer): Max events to return (1-100).
- `startDate` (string): Start date filter (ISO 8601).
- `startingAfter` (string): Event ID cursor for pagination.

### `mercoa_find_transactions` (~216 tokens)

Find transactions

List/search payment transactions. Filter by entity, invoice, status, type and date. GET /transactions.

Input parameters:

- `endDate` (string): CREATED_AT end date filter (ISO 8601).
- `entityGroupId` (string): Filter by entity group ID.
- `entityId`: Filter by entity ID(s) or foreign ID(s).
- `invoiceId`: Filter by invoice ID(s) or foreign ID(s).
- `limit` (integer): Max transactions to return (1-100, default 10).
- `payerId`: Filter by payer ID(s).
- `search` (string): Search by vendor name, invoice number, check number, or amount.
- `startDate` (string): CREATED_AT start date filter (ISO 8601).
- `startingAfter` (string): Transaction ID cursor for pagination.
- `status`: Transaction status filter.
- `transactionId`: Filter by transaction ID(s).
- `transactionType`: Filter by transaction type.
- `vendorId`: Filter by vendor ID(s).

### `mercoa_get_transaction` (~35 tokens)

Get transaction

Get a single payment transaction by ID. GET /transaction/{transactionId}.

Input parameters:

- `transactionId` (string, required): Transaction ID.

### `mercoa_get_organization` (~32 tokens)

Get organization

Get the caller's Mercoa organization configuration (settings, payment methods enabled, etc.). GET /organization.

### `mercoa_create_entity` (~211 tokens)

Create entity

WRITE — creates a real entity (customer/vendor/payor/payee) in Mercoa. Supply role flags, accountType, and a nested `profile` object (business or individual details). POST /entity.

Input parameters:

- `accountType` (string): business or individual.
- `email` (string): Primary email for the entity.
- `foreignId` (string): Your system's ID for this entity.
- `isCustomer` (boolean): Whether this entity has a direct relationship with your organization.
- `isPayee` (boolean): Whether this entity can receive payments (AR / vendor).
- `isPayor` (boolean): Whether this entity can pay invoices (AP).
- `profile` (object): Nested profile object, e.g. { "business": { "legalBusinessName": "Acme Inc.", "email": "ap@acme.com", "businessType": "llc" } } or { "individual": { "name": {...}, "email": "..." } }.

### `mercoa_create_invoice` (~335 tokens)

Create invoice

WRITE — creates a real invoice/bill in Mercoa. Set status (DRAFT to stage, NEW to submit), amount, currency, payer/vendor, dates and line items. POST /invoice.

Input parameters:

- `amount` (number): Total invoice amount.
- `creatorEntityId` (string): Entity ID on whose behalf the invoice is created.
- `creatorUserId` (string): User ID creating the invoice.
- `currency` (string): Currency code, e.g. USD.
- `deductionDate` (string): Scheduled payment/deduction date (ISO 8601).
- `dueDate` (string): Due date (ISO 8601).
- `invoiceDate` (string): Invoice date (ISO 8601).
- `invoiceNumber` (string): Human-readable invoice number, e.g. INV-123.
- `lineItems` (array): Line items array, e.g. [{ "amount": 100, "currency": "USD", "description": "Product A", "quantity": 1, "unitPrice": 100 }].
- `metadata` (object): Arbitrary key/value metadata.
- `noteToSelf` (string): Internal note.
- `payerId` (string): Payer entity ID (who owes).
- `paymentDestinationId` (string): Payment method ID to pay to (vendor's).
- `paymentSourceId` (string): Payment method ID to pay from (payer's).
- `status` (string): Invoice status, e.g. DRAFT, NEW, APPROVED, SCHEDULED.
- `vendorId` (string): Vendor entity ID (who is paid).

### `mercoa_update_invoice` (~266 tokens)

Update invoice

WRITE — updates an existing invoice/bill (all fields optional). Commonly used to advance status (e.g. DRAFT→NEW→SCHEDULED) or change amounts, dates, or payment methods. POST /invoice/{invoiceId}.

Input parameters:

- `amount` (number): Total invoice amount.
- `currency` (string): Currency code, e.g. USD.
- `deductionDate` (string): Scheduled payment/deduction date (ISO 8601).
- `dueDate` (string): Due date (ISO 8601).
- `invoiceDate` (string): Invoice date (ISO 8601).
- `invoiceId` (string, required): Invoice ID to update.
- `invoiceNumber` (string): Human-readable invoice number.
- `lineItems` (array): Replacement line items array.
- `metadata` (object): Arbitrary key/value metadata.
- `noteToSelf` (string): Internal note.
- `payerId` (string): Payer entity ID.
- `paymentDestinationId` (string): Payment method ID to pay to.
- `paymentSourceId` (string): Payment method ID to pay from.
- `status` (string): New invoice status, e.g. NEW, APPROVED, SCHEDULED.
- `vendorId` (string): Vendor entity ID.

### `mercoa_add_invoice_comment` (~75 tokens)

Add invoice comment

WRITE — adds a comment to an invoice (visible in its activity log). POST /invoice/{invoiceId}/comment.

Input parameters:

- `invoiceId` (string, required): Invoice ID to comment on.
- `text` (string, required): Comment text.
- `userId` (string): ID or foreign ID of the user creating the comment.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa#diagnostics

## Score history

- 2026-08-03: 71
- 2026-08-02: 70
- 2026-08-01: 28
- 2026-07-31: 70
- 2026-07-30: 66
- 2026-07-29: 68
- 2026-07-28: 67
- 2026-07-27: 67
- 2026-07-26: 12

## Links

- Remote endpoint: https://mercoa.usefulapi.io/mcp
- Repository: https://github.com/m190/usefulapi-mcp
- Changelog RSS feed: https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa/changelog.json
- HTML version of this page: https://verifymcp.io/servers/io-usefulapi-mercoa/mercoa