Connect an agent to Owedly

1. Choose a resource

Transport: Streamable HTTP, JSON responses, stateless requests. A Resolve token cannot authorize Desk calls.

2. Discover and authorize

Send an unauthenticated request to the MCP URL and follow its WWW-Authenticate resource metadata URL. OAuth discovery: /.well-known/oauth-authorization-server.

Register a public client with a client name, exact redirect URLs, and token_endpoint_auth_method: none. Use authorization code with PKCE S256, a random state of at least 16 characters, and the exact MCP URL as the resource parameter during authorization and token exchange. OpenAPI clients may omit resource when authorization specifies scopes from exactly one workspace; token exchange then uses the existing grant binding. PKCE remains required.

The user reviews permissions in Owedly and can remove permissions or deny the request. Codes expire after two minutes; access tokens after 15 minutes. Refresh tokens rotate and expire after seven days. Reusing a consumed refresh token revokes its grant. Revoke access in Connections & drafts or through the OAuth revocation endpoint.

Client ID metadata documents and confidential-client authentication are not supported in v1. Use dynamic registration with public-client PKCE. Never put credentials or tokens into a prompt.

3. Call a narrow tool

Read tools require the workspace's read scope. Resolve relay_approved_offer reads terms the creditor or agency already approved for a verified account. Acceptance and payment are not available. Draft creation requires its drafts scope and an idempotency key of 16–100 letters, numbers, underscores, or hyphens. Reuse a key only for an identical retry. Changed content with the same key returns a conflict.

Adding a placement requires the signed-in account owner to accept the Desk agreement and approve the draft. Approval adds live accounts and may queue the owner’s configured Account Workflow. Creating the draft alone does not start activity. Consumer drafts can be copied and marked reviewed, but are not sent.

4. Use the API directly

For Muse, use the Muse setup guide and a workspace schema: Desk or Resolve. The combined OpenAPI specification is also available. Tools have POST endpoints under /api/connectors/v1/{workspace}/tools/{tool}, using the same bearer token and JSON arguments as MCP.

POST /api/connectors/v1/desk/tools/list_accounts
Authorization: Bearer <access_token>
Content-Type: application/json

{"limit":20}

Errors: 400 invalid input, 401 expired connection, 403 missing permission, 404 unavailable record, 409 idempotency conflict, 429 rate limit, and 503 service unavailable. Retry reads with backoff. Keep the original idempotency key for draft retries.

Plugin packages

Download the Owedly Desk plugin or Owedly Resolve plugin for clients that support local plugin packages. Each includes its MCP endpoint and a workflow skill. Import support depends on your client; downloading a package does not install or authorize a connection.

Data and release boundaries

Account reads return face amounts and recorded status, not calculated payoff balances. Responses exclude raw contact details, government identifiers, card data, internal notes, and unrelated account data. Keep regulated or sensitive information out of tool arguments.

Limits: 64 KiB requests, 100 accounts per draft, 50 accounts per page, and 120 authenticated requests per minute per grant. No collection messages, settlement execution, payments, or legal conclusions are available.

Public marketplace submission is separate from custom MCP setup. QuickBooks, Xero, Stripe, Salesforce, and HubSpot direct syncs require provider credentials and end-to-end validation before release.