# Operations and tools This page lists every operation of the agent API and every tool of the MCP server. The [OpenAPI document](/openapi.json) has the request and response schemas. ## Agent API Send the access token as `Authorization: Bearer `. A write takes an `Idempotency-Key` header: the same key with the same request gets the first answer again for 24 hours. The same key with another request gets 422. ### GET /v1/agent/organization {#agent-organization-read} **Read the organization of the agent client** This endpoint returns the organization that the agent client belongs to, and the role of the person in the token. Any scope of the mapleid-agent resource is enough. The token's aud must contain mapleid-agent. 401 with the problem type https://mapleid.ca/problems/agent-client-inactive means that an owner or admin stopped the agent client. 403 means that the person is not a member of the organization, or that the token lacks the scope. Operation ID: `agent-organization-read`. ### PATCH /v1/agent/organization {#agent-organization-rename} **Rename the organization of the agent client** This endpoint changes the name of the organization. The slug does not change. The person in the token must be an owner or admin, and the token must have the scope mapleid.agent.organization.write. 422 means that the name is not valid, for example a name that looks like the name of a Maple app. Operation ID: `agent-organization-rename`. ### GET /v1/agent/organization/billing {#agent-billing-read} **Get the billing page of the agent client's organization** This endpoint returns only the URL of the organization's billing page. It does not return the plan. An agent cannot pay. A person opens the page, signs in and pays there. The token must have the scope mapleid.agent.billing.read. The provider Stripe takes the payment on its own page. The provider receives the name and the MapleID ID of your organization. Stripe also receives the email address and the MapleID ID of the person who subscribes. At checkout, Stripe receives your card, your billing address and your tax ID. Operation ID: `agent-billing-read`. ### POST /v1/agent/organization/billing {#agent-billing-pay} **Refuse a payment by an agent** This endpoint always answers 403 with the problem type https://mapleid.ca/problems/human-action-required. The problem body has billing_page_url. Give that URL to a person: only a person can pay, on MapleID's pages. The provider Stripe takes the payment on its own page. The provider receives the name and the MapleID ID of your organization. Stripe also receives the email address and the MapleID ID of the person who subscribes. At checkout, Stripe receives your card, your billing address and your tax ID. Operation ID: `agent-billing-pay`. ### GET /v1/agent/organization/members {#agent-members-list} **List the members of the agent client's organization** This endpoint lists the members, one page at a time, ordered by user_id. The token must have the scope mapleid.agent.members.read. An owner or admin sees every member. A member sees only their own row. Operation ID: `agent-members-list`. ### DELETE /v1/agent/organization/members/{user_id} {#agent-member-remove} **Remove a member from the agent client's organization** This endpoint removes a person from the organization under the organization's role rules. An owner or admin may remove an admin or a member. Any member may remove themselves. Nobody can remove the owner (409). The token must have the scope mapleid.agent.members.write. The API never changes a role. Operation ID: `agent-member-remove`. ### GET /v1/organizations/{id}/invitations {#invitation-list} **List a team organization's open invitations** An agent client calls this endpoint for its own organization, with the access token of a person who is an owner or admin. It lists the invitations that nobody accepted or revoked yet. An invitation past its date is still listed, with expired set to true. The token rules are those of invitation-create. A first-party app gets 403. Operation ID: `invitation-list`. ### POST /v1/organizations/{id}/invitations {#invitation-create} **Invite a person to a team organization as a member** An agent client calls this endpoint for its own organization, with the access token of a person who is an owner or admin (scope mapleid.organizations.invitations.write). MapleID stores the invitation and emails the link. The invitation is for the member role. email_sent is false when the invitation exists but the email failed. A first-party app gets 403: it invites people to its own team and sends the email with /mot/v1/emails/team-invitations. 403 with the problem type https://mapleid.ca/problems/consent-required means the token lacks the scope. 409 means the address is already a member or already has an invitation waiting. Mailgun (United States) sends this email. It receives the content and the recipient address. The data is stored in the European Union. Operation ID: `invitation-create`. ### DELETE /v1/organizations/{id}/invitations/{invitation_id} {#invitation-revoke} **Revoke an invitation** An agent client calls this endpoint for its own organization, with the access token of a person who is an owner or admin. It withdraws an open invitation, and the link stops working. A first-party app gets 403. 409 means the invitation was already accepted or revoked, or it belongs to another organization. Operation ID: `invitation-revoke`. ## MCP tools The server is at `https://mapleid.ca/mcp`. No tool takes an organization ID. Each tool acts on the organization of the agent client. ### get_organization {#tool-get_organization} Get the organization of this agent client and the role of the person in it. Any scope of the mapleid-agent resource is enough. This tool only reads. ### rename_organization {#tool-rename_organization} Change the name of the organization. The slug does not change. The person must be an owner or admin. This tool needs the scope mapleid.agent.organization.write. This tool changes data. ### list_members {#tool-list_members} List the members of the organization, one page at a time. To get the next page, send next_cursor as cursor. An owner or admin sees every member. A member sees only their own row. This tool needs the scope mapleid.agent.members.read. This tool only reads. ### remove_member {#tool-remove_member} Remove a member from the organization. An owner or admin can remove an admin or a member. A member can remove only their own membership. Nobody can remove the owner. This tool needs the scope mapleid.agent.members.write. This tool removes something. Ask the person before you call it. ### get_billing_page {#tool-get_billing_page} Get the URL of the billing page of the organization. An agent cannot pay. Give the URL to the person. This tool needs the scope mapleid.agent.billing.read. The provider Stripe takes the payment on its own page. The provider receives the name and the MapleID ID of your organization. Stripe also receives the email address and the MapleID ID of the person who subscribes. At checkout, Stripe receives your card, your billing address and your tax ID. This tool only reads. ### create_invitation {#tool-create_invitation} Invite a person to the organization with the member role. MapleID sends the invitation by email. The person must be an owner or admin. This tool needs the scope mapleid.organizations.invitations.write. Mailgun (United States) sends this email. It receives the content and the recipient address. The data is stored in the European Union. This tool changes data. ### list_invitations {#tool-list_invitations} List the open invitations of the organization. The person must be an owner or admin. This tool needs the scope mapleid.organizations.invitations.write. This tool only reads. ### revoke_invitation {#tool-revoke_invitation} Revoke an open invitation. Its link stops working. The person must be an owner or admin. This tool needs the scope mapleid.organizations.invitations.write. This tool removes something. Ask the person before you call it.