Connect an external client

For: the installation owner connecting an external client. Developers can use the MCP and HTTP reference.

You need an installation with HTTPS and the correct application URL. Your client must support remote MCP or the HTTP API.

Made with Pepper provides both interfaces through the same permissions. Agent access starts off. Only the owner can enable access or connect a client.

A client can read permitted records, calculate exact previews and prepare invoice drafts. Issuing an invoice needs the delegated person's approval of that invoice.

These tools do not send email, record payments, export files or change bank and tax settings. No model account is required.

Create a connection

Use a pasted credential if your client supports bearer authentication. The credential works with the MCP server and the HTTP API.

1. Open Settings > Agent connections as the owner.
2. Select Enable agent access.
3. Click Save changes.
4. Enter a Connection name.
5. Enter its Purpose.
6. Choose an active staff member in Delegate as user.
7. Set Expires after (days, 1–30).
8. Select the Permitted access the client needs.
9. Click Create connection.
10. Copy the credential into your client's secret store.
11. Click Close.

The credential appears once. Keep it out of URLs, browser storage, source code and logs. If you lose it, revoke the connection.

Connection addresses shows the MCP server address and HTTP API address after you enable access.

For an MCP client, use the MCP address and its bearer-credential setting. For an HTTP client, send Authorization: Bearer <credential> on each request.

Use a server or command-line client for direct HTTP calls. Browser JavaScript requests with an Origin header fail.

Connect through browser sign-in

Use this method if your MCP client supports OAuth browser sign-in. You do not copy a connection credential.

1. Open Settings > Agent connections as the owner.
2. Select Enable agent access.
3. Click Save changes.
4. Select Let MCP clients sign in through the browser.
5. Click Save changes below that option.
6. Copy the MCP server address into your client's server settings.
7. Start the connection from your client.
8. Sign in to Made with Pepper as the owner.
9. Check the client name and the browser's return address.
10. Clear any Permitted access the client does not need.
11. Choose an active staff member in Delegate as user.
12. Set Expires after (days, 1–30).
13. Click Allow access.

Click Deny if the client or return address is wrong. Allow a return to your own computer only for a connection you started.

The browser returns to the client. The client manages access tokens and refreshes them within the connection's expiry.

Browser sign-in needs the installation at the root of its domain or subdomain. It does not support an installation in a subfolder.

An unregistered client or return address shows This connection request cannot be used. Start a new connection from the client.

Limit the permitted work

A connection acts within the delegated user's current permissions and record access. It cannot add a permission that user lacks.

Active staff with a built-in or custom role can be delegates. Guests cannot hold agent connections.

The list shows tools from modules that are on. Turning a module off removes its tools from both interfaces.

Preview and draft writes need invoices.manage. Customer search needs customers.view. Invoice approval needs invoices.finalize and access to that invoice.

Execution also needs invoices.manage. Keep both invoice permissions in a custom role that can approve and issue.

People reads exclude private contact details, rates, time-off records and sign-in settings. Directory reads can include the person's work email.

See Roles and permissions and Modules.

Connect and review a draft

1. Ask the client to find a permitted customer.
2. Ask it to preview the invoice's exact totals.
3. Save the draft with a new idempotency key.
4. Open the returned document link in Made with Pepper.
5. Check the customer, dates, lines, tax selection, currency and total.
6. Edit the draft if it needs a correction.

For EUR, a minor-unit price of "10001" with quantity "1.25" produces EUR 125.01 before tax. USD gives USD 125.01.

The draft shows Prepared through an agent connection, its connection name and the responsible user. Human edits keep that history.

You can use Review and issue in the app. A client that has execute access can request the separate approval below.

Approve one invoice

Approval permits the client to issue one invoice. Execution is a separate step.

flowchart TD
    accTitle: Approval and execution are separate
    accDescr: The client prepares a request. The delegated person approves or rejects it. Approval permits execution within 10 minutes from preparation. Only successful execution confirms issuance. Expired or stale requests need a new request and decision.
    request["`Client prepares
request`"] --> review{"`Delegated person
reviews`"}
    review -->|Reject| rejected["Rejected"]
    review -->|Approve issue| approved["`Approved
still unissued`"]
    approved --> execute["`Client executes
Pepper checks`"]
    execute -->|Checks pass| issued["`Issued number
confirmed`"]

Preparation and approval issue nothing. Respect a rejection. The client must execute within 10 minutes from preparation. Execution checks the request, draft and current access again. A refused execution does not issue the invoice.

The connection must have Invoices · execute after your approval. The delegated user must have permission to issue the invoice.

1. Ask the client to prepare an issue request for the saved draft.
2. Open the returned review link as the delegated user.
3. Check the connection name, customer, dates, tax and exact total.
4. Open Draft if you need to inspect its lines.
5. Return to the approval page.
6. Click Approve issue if the invoice is correct.

Click Reject to refuse the request. Approving gives the client permission to issue this invoice. It does not issue the invoice itself.

The page shows Approved; the agent can issue it now. The client must execute the approved request within its 10-minute window.

The window starts when the client prepares the request. Approval does not restart it.

Issuing assigns the next invoice number and freezes the invoice. It sends no email and records no payment.

After execution, the approval shows Issued. Check the invoice's assigned number before treating it as issued.

Approval rechecks the draft and connection. A failed check shows Out of date: the draft or the connection changed. Prepare a new request.

An Expired request also needs a new request and a new decision. A saved draft or an approved request does not prove issuance.

Stop access

1. Open Settings > Agent connections.
2. Find the named connection.
3. Click Revoke connection.
4. Read the consequence.
5. Confirm Revoke connection.

To stop all connections, clear Enable agent access. Click Save changes. Enabling access again does not restore revoked credentials.

To stop browser connections, clear Let MCP clients sign in through the browser. Click its Save changes button.

That switch revokes browser connections and their tokens. Pasted-credential connections stay active until their own expiry or revocation.

Expiry, user deactivation, permission changes that end their sessions, owner transfer or a changed application URL can stop access.

A request committed before revocation can finish. Later requests fail. Drafts, issued originals, approval history and request receipts remain.

When a call fails

A validation refusal names the fields to correct. Keep your input. A version conflict needs the latest draft before another update.

Use the same payload and key to retry an uncertain write. A successful identical retry returns its original result without another write.

For refused credentials, check expiry, revocation, the delegated user and the owner. Check HTTPS and host configuration if access is forbidden.

For a pending approval, wait for the person's decision. Do not treat Approved as Issued. Read the result after execution.

The client receives only granted tools. Its access may shrink after a role or module change. See the error reference.

Made with Pepper keeps connection metadata, credential hashes, draft attribution and approval evidence on your server. Revocation does not erase that history.

A client can keep copies of records it read. Revocation cannot remove those copies. See Customer data and privacy.