mercoa
Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.
¿Debería usar esto?
Calidad y seguridad
Hallazgos (2)
- LOWen mercoa_get_entity_invoice_metrics
- LOWen mercoa_list_entity_payment_methods
Basado en el análisis automatizado de las definiciones de herramientas y el cumplimiento del protocolo.
Costo de contexto
Este es el número aproximado de tokens que se consumen cada vez que las herramientas del servidor se cargan en el contexto de un modelo. Los recuentos más altos reducen la atención disponible para otras tareas.
Instalar
Instalación con un clic
Agrega esto a tu archivo `claude_desktop_config.json`:
{
"mcpServers": {
"mercoa": {
"url": "https://mercoa.usefulapi.io/mcp"
}
}
}Puntos de conexión remotos
https://mercoa.usefulapi.io/mcpstreamable-httpQué puede hacer
Inventario de herramientas
Herramientas (17)
🟢mercoa_find_entities(search, isCustomer, isPayor, isPayee, foreignId, ...)
Find/search entities (buyers, vendors, payors, payees). Use to look up counterparties by name/email/foreignId or list all. GET /entity.
Esquema de entrada
{
"type": "object",
"properties": {
"search": {
"description": "Search by name, email, emailTo, entity ID, or foreign ID (partial matches).",
"type": "string"
},
"isCustomer": {
"description": "If true, only entities with a direct relationship to your organization.",
"type": "boolean"
},
"isPayor": {
"description": "Filter entities marked as payors.",
"type": "boolean"
},
"isPayee": {
"description": "Filter entities marked as payees.",
"type": "boolean"
},
"foreignId": {
"description": "Your system's ID(s) for the entity.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"status": {
"description": "Entity status filter (e.g. verified, pending).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"paymentMethods": {
"description": "If true, include payment methods in the response.",
"type": "boolean"
},
"returnMetadata": {
"description": "Metadata key(s) to include in the response.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"limit": {
"description": "Max entities to return (1-100, default 10).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
},
"startingAfter": {
"description": "Entity ID cursor for pagination.",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_entity(entityId)
Get a single entity by ID (or foreign ID). GET /entity/{entityId}.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID (e.g. ent_...) or foreign ID."
}
},
"required": [
"entityId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_entity_events(entityId, startDate, endDate, limit, startingAfter)
Get the event/audit log for an entity. GET /entity/{entityId}/events.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID or foreign ID."
},
"startDate": {
"description": "Start date filter (ISO 8601).",
"type": "string"
},
"endDate": {
"description": "End date filter (ISO 8601).",
"type": "string"
},
"limit": {
"description": "Max events to return (1-100).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
},
"startingAfter": {
"description": "Event ID cursor for pagination.",
"type": "string"
}
},
"required": [
"entityId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_entity_invoice_metrics(entityId, search, excludePayables, excludeReceivables, returnByDate, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID or foreign ID."
},
"search": {
"description": "Search by vendor name, invoice number, check number, or amount.",
"type": "string"
},
"excludePayables": {
"description": "Only return receivables (exclude payables).",
"type": "boolean"
},
"excludeReceivables": {
"description": "Only return payables (exclude receivables).",
"type": "boolean"
},
"returnByDate": {
"description": "Group metrics by date, e.g. CREATION_DATE or DUE_DATE.",
"type": "string"
},
"returnByDateFrequency": {
"description": "Frequency for date grouping (e.g. DAILY, MONTHLY).",
"type": "string"
},
"groupBy": {
"description": "Additional grouping (e.g. by status).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"payerId": {
"description": "Filter by payer ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"vendorId": {
"description": "Filter by vendor ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"approverId": {
"description": "Filter by assigned approver user ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"invoiceId": {
"description": "Filter by invoice ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"status": {
"description": "Invoice status filter (e.g. NEW, SCHEDULED, PAID).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"startDate": {
"description": "Start date filter (ISO 8601).",
"type": "string"
},
"endDate": {
"description": "End date filter (ISO 8601).",
"type": "string"
},
"dateType": {
"description": "Date type to filter by (e.g. CREATED_AT, DUE_DATE).",
"type": "string"
},
"currency": {
"description": "Currency code(s) to filter on, e.g. USD.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"required": [
"entityId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_list_entity_payment_methods(entityId, type)
List an entity's payment methods (bank accounts, cards, check, etc.). GET /entity/{entityId}/paymentMethods.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID or foreign ID."
},
"type": {
"description": "Filter by payment method type (e.g. bankAccount, card, check).",
"type": "string"
}
},
"required": [
"entityId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_payment_method(entityId, paymentMethodId)
Get a single payment method for an entity. GET /entity/{entityId}/paymentMethod/{paymentMethodId}.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID or foreign ID."
},
"paymentMethodId": {
"type": "string",
"description": "Payment method ID (e.g. pm_...)."
}
},
"required": [
"entityId",
"paymentMethodId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_list_entity_users(entityId)
List the users belonging to an entity (approvers, admins, etc.). GET /entity/{entityId}/users.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"type": "string",
"description": "Entity ID or foreign ID."
}
},
"required": [
"entityId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_find_invoices(entityId, entityGroupId, status, payerId, vendorId, ...)
Find/search invoices (bills) across payers and vendors. Filter by status, entity, date, approver and more. GET /invoices (plural list endpoint).
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"description": "Filter by entity (payer or vendor) ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"entityGroupId": {
"description": "Filter by entity group ID.",
"type": "string"
},
"status": {
"description": "Invoice status filter (e.g. DRAFT, NEW, APPROVED, SCHEDULED, PAID).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"payerId": {
"description": "Filter by payer ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"vendorId": {
"description": "Filter by vendor ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"invoiceId": {
"description": "Filter by invoice ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"search": {
"description": "Search by vendor name, invoice number, check number, or amount.",
"type": "string"
},
"startDate": {
"description": "Start date filter (ISO 8601).",
"type": "string"
},
"endDate": {
"description": "End date filter (ISO 8601).",
"type": "string"
},
"dateType": {
"description": "Date type to filter by (e.g. CREATED_AT, DUE_DATE).",
"type": "string"
},
"orderBy": {
"description": "Field to order by (e.g. CREATED_AT, AMOUNT, DUE_DATE).",
"type": "string"
},
"orderDirection": {
"description": "asc or desc.",
"type": "string"
},
"paymentType": {
"description": "Filter by payment type (e.g. recurring).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"approverId": {
"description": "Filter by assigned approver user ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"approverAction": {
"description": "Filter by approver action (use with approverId), e.g. APPROVE.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"creatorUserId": {
"description": "Filter by the user ID(s) that created the invoice.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"invoiceTemplateId": {
"description": "Filter by invoice template ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"returnPayerMetadata": {
"description": "Include payer metadata in the response.",
"type": "boolean"
},
"returnVendorMetadata": {
"description": "Include vendor metadata in the response.",
"type": "boolean"
},
"returnPaymentTiming": {
"description": "Include payment timing in the response.",
"type": "boolean"
},
"limit": {
"description": "Max invoices to return (1-100, default 10).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
},
"startingAfter": {
"description": "Invoice ID cursor for pagination.",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_invoice(invoiceId)
Get a single invoice (bill) by ID. GET /invoice/{invoiceId}.
Esquema de entrada
{
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"description": "Invoice ID (e.g. in_...) or foreign ID."
}
},
"required": [
"invoiceId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_invoice_events(invoiceId, startDate, endDate, limit, startingAfter)
Get the event/audit log for an invoice (status changes, approvals, payments). GET /invoice/{invoiceId}/events.
Esquema de entrada
{
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"description": "Invoice ID or foreign ID."
},
"startDate": {
"description": "Start date filter (ISO 8601).",
"type": "string"
},
"endDate": {
"description": "End date filter (ISO 8601).",
"type": "string"
},
"limit": {
"description": "Max events to return (1-100).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
},
"startingAfter": {
"description": "Event ID cursor for pagination.",
"type": "string"
}
},
"required": [
"invoiceId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_find_transactions(entityId, entityGroupId, payerId, vendorId, invoiceId, ...)
List/search payment transactions. Filter by entity, invoice, status, type and date. GET /transactions.
Esquema de entrada
{
"type": "object",
"properties": {
"entityId": {
"description": "Filter by entity ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"entityGroupId": {
"description": "Filter by entity group ID.",
"type": "string"
},
"payerId": {
"description": "Filter by payer ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"vendorId": {
"description": "Filter by vendor ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"invoiceId": {
"description": "Filter by invoice ID(s) or foreign ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"transactionId": {
"description": "Filter by transaction ID(s).",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"status": {
"description": "Transaction status filter.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"transactionType": {
"description": "Filter by transaction type.",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"search": {
"description": "Search by vendor name, invoice number, check number, or amount.",
"type": "string"
},
"startDate": {
"description": "CREATED_AT start date filter (ISO 8601).",
"type": "string"
},
"endDate": {
"description": "CREATED_AT end date filter (ISO 8601).",
"type": "string"
},
"limit": {
"description": "Max transactions to return (1-100, default 10).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
},
"startingAfter": {
"description": "Transaction ID cursor for pagination.",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_transaction(transactionId)
Get a single payment transaction by ID. GET /transaction/{transactionId}.
Esquema de entrada
{
"type": "object",
"properties": {
"transactionId": {
"type": "string",
"description": "Transaction ID."
}
},
"required": [
"transactionId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢mercoa_get_organization
Get the caller's Mercoa organization configuration (settings, payment methods enabled, etc.). GET /organization.
Esquema de entrada
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴mercoa_create_entity(isCustomer, isPayor, isPayee, accountType, foreignId, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"isCustomer": {
"description": "Whether this entity has a direct relationship with your organization.",
"type": "boolean"
},
"isPayor": {
"description": "Whether this entity can pay invoices (AP).",
"type": "boolean"
},
"isPayee": {
"description": "Whether this entity can receive payments (AR / vendor).",
"type": "boolean"
},
"accountType": {
"description": "business or individual.",
"type": "string",
"enum": [
"business",
"individual"
]
},
"foreignId": {
"description": "Your system's ID for this entity.",
"type": "string"
},
"email": {
"description": "Primary email for the entity.",
"type": "string"
},
"profile": {
"description": "Nested profile object, e.g. { \"business\": { \"legalBusinessName\": \"Acme Inc.\", \"email\": \"[email protected]\", \"businessType\": \"llc\" } } or { \"individual\": { \"name\": {...}, \"email\": \"...\" } }.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴mercoa_create_invoice(status, amount, currency, payerId, vendorId, ...)
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.
Esquema de entrada
{
"type": "object",
"properties": {
"status": {
"description": "Invoice status, e.g. DRAFT, NEW, APPROVED, SCHEDULED.",
"type": "string"
},
"amount": {
"description": "Total invoice amount.",
"type": "number"
},
"currency": {
"description": "Currency code, e.g. USD.",
"type": "string"
},
"payerId": {
"description": "Payer entity ID (who owes).",
"type": "string"
},
"vendorId": {
"description": "Vendor entity ID (who is paid).",
"type": "string"
},
"creatorEntityId": {
"description": "Entity ID on whose behalf the invoice is created.",
"type": "string"
},
"creatorUserId": {
"description": "User ID creating the invoice.",
"type": "string"
},
"invoiceDate": {
"description": "Invoice date (ISO 8601).",
"type": "string"
},
"dueDate": {
"description": "Due date (ISO 8601).",
"type": "string"
},
"deductionDate": {
"description": "Scheduled payment/deduction date (ISO 8601).",
"type": "string"
},
"invoiceNumber": {
"description": "Human-readable invoice number, e.g. INV-123.",
"type": "string"
},
"noteToSelf": {
"description": "Internal note.",
"type": "string"
},
"paymentSourceId": {
"description": "Payment method ID to pay from (payer's).",
"type": "string"
},
"paymentDestinationId": {
"description": "Payment method ID to pay to (vendor's).",
"type": "string"
},
"lineItems": {
"description": "Line items array, e.g. [{ \"amount\": 100, \"currency\": \"USD\", \"description\": \"Product A\", \"quantity\": 1, \"unitPrice\": 100 }].",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"metadata": {
"description": "Arbitrary key/value metadata.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴mercoa_update_invoice(invoiceId, status, amount, currency, payerId, ...)
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}.
Esquema de entrada
{
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"description": "Invoice ID to update."
},
"status": {
"description": "New invoice status, e.g. NEW, APPROVED, SCHEDULED.",
"type": "string"
},
"amount": {
"description": "Total invoice amount.",
"type": "number"
},
"currency": {
"description": "Currency code, e.g. USD.",
"type": "string"
},
"payerId": {
"description": "Payer entity ID.",
"type": "string"
},
"vendorId": {
"description": "Vendor entity ID.",
"type": "string"
},
"invoiceDate": {
"description": "Invoice date (ISO 8601).",
"type": "string"
},
"dueDate": {
"description": "Due date (ISO 8601).",
"type": "string"
},
"deductionDate": {
"description": "Scheduled payment/deduction date (ISO 8601).",
"type": "string"
},
"invoiceNumber": {
"description": "Human-readable invoice number.",
"type": "string"
},
"noteToSelf": {
"description": "Internal note.",
"type": "string"
},
"paymentSourceId": {
"description": "Payment method ID to pay from.",
"type": "string"
},
"paymentDestinationId": {
"description": "Payment method ID to pay to.",
"type": "string"
},
"lineItems": {
"description": "Replacement line items array.",
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"metadata": {
"description": "Arbitrary key/value metadata.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"invoiceId"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🔴mercoa_add_invoice_comment(invoiceId, text, userId)
WRITE — adds a comment to an invoice (visible in its activity log). POST /invoice/{invoiceId}/comment.
Esquema de entrada
{
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"description": "Invoice ID to comment on."
},
"text": {
"type": "string",
"description": "Comment text."
},
"userId": {
"description": "ID or foreign ID of the user creating the comment.",
"type": "string"
}
},
"required": [
"invoiceId",
"text"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Prompts recomendados
mercoa_get_entitymercoa_find_entitiesmercoa_get_entitymercoa_find_entitiesmercoa_list_entity_payment_methodsComunidad
Evidencia