ApproveIt MCP server

Let Claude, Cursor or your own agent read and act on ApproveIt approvals as a specific person in a specific workspace.

ApproveIt runs a remote Model Context Protocol server. An AI host
such as Claude Desktop, Claude Code or Cursor, or an agent you write yourself, can list workflows,
read approval requests, submit new ones and record approval decisions, without you building
anything against the REST API first.

Everything the server exposes runs as one specific person in one specific workspace, fixed by
the credential the host connects with. There is no way to act as another user, and no way to read
another workspace. A connected app sees exactly what that person sees in the web app, because every
tool goes through the same permissions and the same per-request access rules as the UI.

📘

Who can connect

Any active member of an ApproveIt workspace whose role includes Connect an AI app. Workspace
administrators have it by default. Where the Roles tab is available, an administrator can grant it
to other roles under Team → Roles. It controls one thing: whether you may open a connection at all.
What you can do once connected is decided entirely by the rest of your role, so a connection can
never see or do more than you can in the web app. Suspending someone cuts off their AI connections
along with their web access, and an administrator can switch the whole workspace off under
Workspace Settings → Integrations → Approveit MCP.

Endpoint

URLhttps://api.approveit.today/mcp
TransportStreamable HTTP, JSON responses
MethodPOST only
Protocol versions2025-06-18, 2025-03-26
Server nameapproveit

The endpoint is stateless. There is no Mcp-Session-Id, no SSE stream and no standing GET
stream, so GET and DELETE answer 405. Every request re-authenticates, which is also why
revoking access takes effect on the very next call rather than when a session expires.

Connect

Option 1: OAuth (recommended)

The server is a full OAuth 2.1 authorization server with discovery and dynamic client
registration, so a host that has never seen ApproveIt can offer a "Connect" button with no
credentials created up front.

In your AI host, add a remote MCP server with the endpoint URL above. The host then:

  1. reads https://api.approveit.today/.well-known/oauth-protected-resource (RFC 9728) and
    /.well-known/oauth-authorization-server (RFC 8414);
  2. registers itself at /mcp/oauth/register (RFC 7591) if it has no client id yet;
  3. opens /mcp/oauth/authorize, which sends you to the ApproveIt web app to sign in with whatever
    your workspace already uses (password, Google, Microsoft, Slack, Webex, SAML SSO, MFA) and show
    a consent screen;
  4. exchanges the returned code at /mcp/oauth/token with PKCE.

On the consent screen you pick which workspace the connection acts in, if you belong to more
than one, and you see which application is asking. Access tokens last one hour; refresh tokens last
30 days and rotate on every use.

Rotation is what makes a stolen refresh token detectable: when a token that has already been
exchanged is presented again, every live token for that person and application is revoked, and the
connection has to be authorized afresh. Worth being precise about what that does and does not
promise. Whoever uses the token second is the one who trips the detection, so an attacker who
gets in first holds a working replacement until the real client next refreshes — detection ends the
session for both of them, it does not retroactively protect the window before it. If you believe a
key or a connection has leaked, disconnect it from Profile settings → Connected AI apps rather
than waiting for rotation to notice.

Supported grants are authorization_code and refresh_token. PKCE is mandatory and S256 only.
Scopes are read and write (see Scopes).

To see or undo a connection, open the ApproveIt web app and go to Profile settings → Connected AI
apps
. Disconnecting revokes the application's tokens immediately.

Option 2: API key

For a server-side agent, a script or anywhere no browser is available, there is nobody to click
Connect, so OAuth cannot help. Create a long-lived key instead: in the ApproveIt web app, open
Profile settings → Connected AI apps → API keys, give it a name, choose read or read and write,
and optionally an expiry.

The key is shown once, at creation. Copy it then; ApproveIt stores only a hash and cannot show
it again. If you lose it, revoke it and create another.

A key is bound to one person in one workspace permanently, and acts as that person: it can never do
more than their role allows, and anything it does is attributed to them. Keys look like
apit_mcp_us_<random>. You can hold up to 10 active keys per workspace, and revoke any of them from
the same screen — revocation takes effect on the key's next call.

Present it as a bearer token:

{
  "mcpServers": {
    "approveit": {
      "url": "https://api.approveit.today/mcp",
      "headers": { "Authorization": "Bearer apit_mcp_us_..." }
    }
  }
}

If a key leaks, revoke it on that same screen. Revocation is immediate and permanent, and the key's
past activity stays in the audit trail.

Scopes

ScopeAllows
readEvery listing, lookup and reporting tool.
writeThe action tools: submit, update, approve, reject, cancel, invite, create or activate a workflow. Implies read.

A credential with no scope can do nothing at all.

A scope is a ceiling, never a grant. On top of it, every tool call is checked against the
connected person's role permissions, and then against the per-request access rules. A write
credential held by someone who is not the current approver on a request still cannot approve it.
tools/list is filtered by both the scope and the person's permissions, so a read-only connection
is never shown an action tool it would only fail at.

Tools

21 tools are published. Everything in the table needs read unless the Scope column says write.

Each tool's arguments come from tools/list as a JSON Schema, and that schema is the authoritative
list. An argument the tool does not declare is rejected with a message naming the ones it accepts,
rather than being silently ignored, so a mistyped filter can never look like a filter that matched
everything.

Identity

ToolScopeAlso requires
get_user_contextreadNothing. Returns the name, email, role, department and workspace this connection acts as.

Workflows

ToolScopeAlso requires
list_workflowsreadworkflow.view
get_workflow_detailsreadworkflow.view. The field list, types, required flags and option sets. Call before submitting.
describe_workflowreadworkflow.view. Approval steps, approvers per step, routing conditions.
list_workflow_templatesreadworkflow.view
describe_workflow_templatereadworkflow.view
create_workflow_from_templatewriteworkflow.add. Goes live at once when it can take requests; active in the result says whether it did.
activate_workflowwriteworkflow.change and workflow.add. Idempotent.

Approval requests

ToolScopeAlso requires
list_approval_requestsreadrequest.view. Filter by status, scope (created_by_me, awaiting_my_approval), workflow, submission date, free text, or by a form field's value. Paged: read count and truncated.
describe_approval_requestreadrequest.view. Accepts AR-15 or the internal id.
get_request_activityreadrequest.view. The chronological audit trail.
summarize_approvalsreadrequest.view. Totals what a person approved in a date range, by currency.
analyze_fieldreadrequest.view. Database aggregate over any field, including line-item columns, with grouping. Sums, averages, max and min leave out draft, rejected and canceled requests unless status names them; status_scope in the result says what was counted.
submit_requestwriterequest.add
update_requestwriterequest.view, plus you submitted it and it is still open.
approve_requestwriterequest.view, plus you are the current pending approver.
reject_requestwriterequest.view, plus you are the current pending approver.
cancel_requestwriterequest.view, plus you submitted it.

Lookups and team

ToolScopeAlso requires
search_entitiesreadrequest.add. Resolves vendors, customers, departments, locations, cost centers, categories, taxes and products to the ids a form expects.
search_team_usersreadteam.view
invite_team_memberwriteteam.invite_member. Sends real email.

Tools are annotated with readOnlyHint, destructiveHint and idempotentHint so a host can
prompt before running one. Approve, reject and cancel are marked destructive. Those annotations are
a courtesy to the host, not a control; the controls are the scope and the permissions.

Safety behaviour you should expect

Actions are real. Approving, rejecting, cancelling, submitting and inviting notify real people
and are recorded as decisions of record against the connected person. Hosts are instructed, in the
server's own instructions field, to show the user what will happen and get explicit confirmation
in the same turn. Field values and comments inside a request are treated as user content, never as
directions to the model.

A preview comes first. Submitting, updating, approving, rejecting, cancelling and inviting each
take confirmed. Without it the call returns a preview and writes nothing. With confirmed: true,
the server runs the action only if the same credential previewed the same arguments in the last 10
minutes and the request has not changed since. Otherwise the call runs as that preview, marked
preview_required, and writes nothing. One preview admits one attempt, so a call that fails needs a
new one. This proves a preview was returned, not that a person read it or agreed: a host that sends
confirmed: true twice commits on the second call, so showing the preview and asking stays the
host's job. If the server cannot reach its preview store it does not hold the call back, so always
preview first regardless.

Duplicate writes are absorbed. An identical write call (same credential, same tool, same
arguments) inside 90 seconds returns the first call's result, marked as a replay, rather than
running again. A host that retries after a timeout does not create a second purchase order. An
identical call still in flight is refused with a message saying so. Reads are never replayed. One
exception: on a tool acting on an existing request (approve, reject, cancel, update), a new preview
clears the stored result, so preview, confirm, preview, confirm acts twice. The yes to a fresh
preview is a new decision, and a request can have moved on since the first. submit_request keeps
its replay, so a host that re-previews a submission after a lost response does not create a second
request.

You get told out of band. When a connected application approves, rejects, cancels or submits as
you, ApproveIt emails you saying which application did what, and how to disconnect it. That is
deliberate: it reaches you even when the application itself is misbehaving.

Everything is logged. Every tool call is recorded with the credential, the person, the tool,
the outcome and the duration, whether it succeeded, was denied, was rate limited or crashed. In the
web app, the Actions page lists AI activity and filters to inbound calls, which is what
connected apps did. Seeing inbound rows there requires the integration management permission.

Security and data handling

The question a security review usually opens with is "what does ApproveIt send to an AI vendor".
The answer is nothing. ApproveIt does not transmit your data to any AI provider for this
feature. Your own AI application connects to ApproveIt and reads what it asks for, using a
credential your own user authorized. Which AI vendor that is, and what they may do with the data
once it reaches them, is your choice and your contract with them, exactly as it would be if your
employee had copied the same information into that tool by hand.

What that means in practice:

QuestionAnswer
Who can connect?Any active member of your workspace, with their own credential. An administrator can switch the whole workspace off.
What can a connection see?Exactly what that person sees in the web app. Role permissions and per-request access rules are applied on every call, not at connection time.
Can it act as someone else?No. The workspace and the person are fixed by the credential. There is no parameter anywhere in the protocol that changes either.
Can it reach another workspace?No, including for people who belong to several. One connection is one workspace, chosen at consent time.
What is recorded?Every call: who, which tool, the outcome, how long it took. Approvals and rejections also land in the request's own audit trail, marked as having come from a connected application.
How do we stop it?Disconnect the application in Profile settings, or an administrator switches the workspace off. Either takes effect on the connection's next call, because credentials are checked against the database every time rather than cached.
What if an application misbehaves?Whenever a connected application approves, rejects, cancels or submits as you, ApproveIt emails you saying what happened and how to disconnect it. That notice is sent out of band so it reaches you even if the application itself is the problem.

Two limits worth stating plainly rather than leaving you to discover them. A connected application
reads request titles, field values and comments, which are text your own people wrote; a model can
be influenced by text it reads, which is why approving requires the person to be the genuine
pending approver and why read-only is the default. And the advisory hints ApproveIt sends about
which tools are destructive are honoured at the AI host's discretion, not enforced by us — the
enforcement is the permission system.

Rate limits

LimitCeiling
Calls per credential120 per minute
Write calls per credential20 per minute. A preview counts as a read, not a write.
Calls per workspace, all credentials300 per minute
Dynamic client registrations per IP10 per minute

Over a limit, the tool returns an error result naming the seconds to wait, so the model can wait
rather than report a broken connector. Separately, a small number of calls run at once per server
process; a call that arrives while they are all busy waits a couple of seconds for a turn, and only
if none comes free does the endpoint answer 503 with a Retry-After header. Wait the number of
seconds it gives you before retrying.

A single call is also given a fixed budget of database time, currently 15 seconds. A call that
exceeds it is cancelled. Retrying the same request will hit the same limit, so narrow it instead: a
shorter date range, fewer results, a more specific filter. Depending on where the limit was reached,
you will see either "The request took too long and was cancelled" or a tool error naming
OperationalError; both mean the same thing.

Request bodies are capped at 1 MiB (1,048,576 bytes). Very large tool results are truncated with a
notice, and a truncated result omits structuredContent.

Error reference

JSON-RPC errors ride on HTTP 200, because the failure is at application level and retrying the
same request would fail identically. The HTTP status changes only when the transport itself did.

What you seeWhat it means
401 with WWW-Authenticate: Bearer resource_metadata=...No credential, or an invalid, expired or revoked one. The header points at discovery so a host can start OAuth.
401 about AI connections not being availableOne of four things, and the message says which: your role is missing Connect an AI app, the workspace switched AI connections off, the plan does not include them, or ApproveIt has disabled them for the workspace. Each message names who can change it and where.
401 "This account is not active."The member is suspended or deleted in ApproveIt.
400 "Unsupported MCP-Protocol-Version"Your client negotiated a version this server does not speak.
405You sent GET or DELETE. Use POST.
413Body over 1 MiB.
503 with Retry-AfterAt capacity after waiting for a turn. Retry after the stated delay.
-32603 "The request took too long and was cancelled"The call exceeded its database time budget. Narrow the request; retrying it unchanged will not help.
Result with isError naming OperationalErrorUsually the same time budget, reached inside a tool. Treated the same way: narrow the request.
Result with isError, "needs the 'write' scope"Read-only connection. Reconnect the application asking for write, or request a write-scoped key.
Result with isError, "You do not have permission"The person's role does not carry the permission that tool needs. An admin can change their role.
Result with isError, "Unknown argument(s)"The arguments you sent are not the ones the tool declares. The message lists the accepted names; do not retry with guesses.
-32601 Method not foundOnly initialize, ping, tools/list and tools/call are implemented.

Try it with curl

Handshake:

curl -s https://api.approveit.today/mcp \
  -H "Authorization: Bearer $APPROVEIT_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'

List what this credential may call:

curl -s https://api.approveit.today/mcp \
  -H "Authorization: Bearer $APPROVEIT_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Call one:

curl -s https://api.approveit.today/mcp \
  -H "Authorization: Bearer $APPROVEIT_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"list_approval_requests",
                 "arguments":{"scope":"awaiting_my_approval","limit":10}}}'

To inspect the server interactively:

npx @modelcontextprotocol/inspector

Current limitations

  • No streaming. JSON responses only. No SSE, no server-initiated messages, so no sampling or
    elicitation.
  • No tools/list pagination. The full list returns in one page. Fine at 21 tools.
  • No workspace-wide view of connections. You can see and revoke your own connections and keys.
    An administrator who needs the picture across everyone has to ask us.
  • Verified with Claude. Claude Desktop, Claude Code and plain HTTP clients are tested end to
    end. Other hosts implement the same specification and should work, but we have not certified
    them, so tell us if one behaves oddly.
  • Prompt injection is mitigated, not eliminated. What protects you is structural: read-only by
    default, role permissions, the rule that only the genuine pending approver can approve, and the
    out-of-band email when an action is taken. The advisory hints a host reads can be ignored by that
    host.

How this differs from the REST API

The REST API uses a workspace-level token and acts as the
workspace, not as a person. That is right for server-to-server integration, and wrong for approvals,
because an approval has to be attributable to a person and has to run through that person's
permissions. The MCP credential is per person by construction, which is why the two are separate
and why MCP is the surface an AI assistant should use.