Tools reference

This page documents every MCP tool exposed by swapps-app-mcp (defined in server.py). All tools are read-only: each one issues a single authenticated GET request against the swapps-app DRF API and returns the JSON response serialized as a string.

Common behavior

  • Endpoints are relative to SWAPPS_API_BASE_URL (for example https://app.swapps.com/api).
  • Every request sends Authorization: Token <SWAPPS_API_TOKEN> and Accept: application/json.
  • Results are returned as pretty-printed JSON. Non-2xx responses come back as a readable HTTP <status> error ... string rather than raising.
  • list_* tools accept an optional params dict that is forwarded verbatim as DRF query parameters (filters, search, pagination). The exact supported keys depend on the swapps-app API; common ones are search, page, and resource-specific filters.

Overview

Tool Purpose Endpoint (GET)
list_clients List clients clients/
get_client Get one client by ID clients/{pk}/
list_contracts List contracts contracts/
get_contract Get one contract by ID contracts/{pk}/
list_contract_services List a contract's services contracts/{contract_pk}/services/
get_contract_service Get one service of a contract contracts/{contract_pk}/services/{pk}/
list_contract_installments List a contract's installments contracts/{contract_pk}/installments/
get_contract_installment Get one installment of a contract contracts/{contract_pk}/installments/{pk}/
list_contract_level_rates List a contract's level rates contracts/{contract_pk}/level-rates/
get_contract_level_rate Get one level rate of a contract contracts/{contract_pk}/level-rates/{pk}/
list_reports List reports reports/
get_report Get one report by ID reports/{pk}/
list_tasks List tasks tasks/
get_task Get one task by ID tasks/{pk}/
list_time_entries List time entries time-entries/
get_time_entry Get one time entry by ID time-entries/{pk}/
list_subscriptions List subscriptions (role-scoped) subscriptions/
get_subscription Get one subscription by ID subscriptions/{pk}/
get_subscription_payments List a subscription's payment history subscriptions/{pk}/payments/
list_subscription_plans List public subscription plans subscription-plans/
get_celery_task_status Poll a Celery task's status get-task-status/
api_request Read-only escape hatch: GET any API path {path}

Clients

list_clients

List the clients registered in swapps-app.

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination, e.g. {"search": "acme", "page": 2}.

Hits GET clients/.

get_client

Get a single client by its numeric ID.

Param Type Required Description
pk int Yes Numeric client ID.

Hits GET clients/{pk}/.

Contracts

Contracts have three nested sub-resources — services, installments, and level rates — each addressed under the parent contract.

list_contracts

List contracts.

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination.

Hits GET contracts/.

get_contract

Get a single contract by its numeric ID.

Param Type Required Description
pk int Yes Numeric contract ID.

Hits GET contracts/{pk}/.

list_contract_services

List the services of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
params dict No Optional DRF query params for filtering/pagination.

Hits GET contracts/{contract_pk}/services/.

get_contract_service

Get a single service of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
pk int Yes Service ID within the contract.

Hits GET contracts/{contract_pk}/services/{pk}/.

list_contract_installments

List the installments (payment schedule) of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
params dict No Optional DRF query params for filtering/pagination.

Hits GET contracts/{contract_pk}/installments/.

get_contract_installment

Get a single installment of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
pk int Yes Installment ID within the contract.

Hits GET contracts/{contract_pk}/installments/{pk}/.

list_contract_level_rates

List the per-level rates of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
params dict No Optional DRF query params for filtering/pagination.

Hits GET contracts/{contract_pk}/level-rates/.

get_contract_level_rate

Get a single level rate of a contract.

Param Type Required Description
contract_pk int Yes Parent contract ID.
pk int Yes Level-rate ID within the contract.

Hits GET contracts/{contract_pk}/level-rates/{pk}/.

Reports

list_reports

List reports.

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination.

Hits GET reports/.

get_report

Get a single report by its numeric ID.

Param Type Required Description
pk int Yes Numeric report ID.

Hits GET reports/{pk}/.

Tasks

list_tasks

List tasks.

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination, e.g. {"status": "open"}.

Hits GET tasks/.

get_task

Get a single task by its numeric ID.

Param Type Required Description
pk int Yes Numeric task ID.

Hits GET tasks/{pk}/.

Time entries

list_time_entries

List time entries.

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination, e.g. {"date_after": "2026-06-01"} (available filters depend on the API).

Hits GET time-entries/.

get_time_entry

Get a single time entry by its numeric ID.

Param Type Required Description
pk int Yes Numeric time-entry ID.

Hits GET time-entries/{pk}/.

Subscriptions

The subscription graph — subscriptions, their payment history, and the public plan catalog. Reads are role-scoped server-side: an admin token sees every subscription, while a non-admin token only sees subscriptions belonging to the companies its user is a member of. A get_* on a subscription outside the token's scope returns HTTP 404. These tools never widen that scope — they only issue GET requests with the caller's token.

list_subscriptions

List the subscriptions visible to the token (already filtered by role).

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination.

Hits GET subscriptions/.

get_subscription

Get a single subscription by its numeric ID. Returns 404 if it is outside the token's role scope.

Param Type Required Description
pk int Yes Numeric subscription ID.

Hits GET subscriptions/{pk}/.

get_subscription_payments

List the payment history of a subscription.

Param Type Required Description
pk int Yes Numeric subscription ID.

Hits GET subscriptions/{pk}/payments/.

list_subscription_plans

List the public subscription plans (the pricing catalog).

Param Type Required Description
params dict No Optional DRF query params for filtering/pagination.

Hits GET subscription-plans/.

Miscellaneous

get_celery_task_status

Poll the status of a Celery background task via the swapps-app get-task-status/ endpoint.

Param Type Required Description
task_id str No Celery task ID. When provided, it is sent as the task_id query param; when empty, the endpoint is called with no params.

Hits GET get-task-status/ (with ?task_id=<task_id> when supplied).

api_request

Read-only escape hatch for endpoints or query params the typed helpers above do not cover. It performs a GET only — it cannot create, update, or delete.

Param Type Required Description
path str Yes Path relative to SWAPPS_API_BASE_URL, e.g. "tasks/" or "contracts/5/services/". A leading slash is optional.
params dict No Optional query params (filters, pagination, etc.).

Hits GET {path}.

When to use api_request

Reach for api_request when you need an endpoint without a dedicated tool, or an unusual combination of query parameters. Because it is GET-only, it preserves the server's read-only guarantee.