portkey-admin-mcp

invite_user

Invite a new organization user by email with an org role, and optionally grant workspace access and create an API key in the same call.

Instructions

Invite a new org user and optionally provision workspace access and an API key in one call. Workspace assignments apply only after acceptance; use add_workspace_member or update_workspace_member later for follow-up changes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "email": "<email>",
      "role": "<role>",
      "workspaces": "<workspaces>"
    },
    "name": "invite_user"
  }
}

Input Schema

Name	Required	Description
`role`	Yes	Organization-level role: 'admin' for full access, 'member' for limited access
`email`	Yes	Email address of the user to invite
`last_name`	No	User's last name
`first_name`	No	User's first name
`workspaces`	Yes	List of workspaces and corresponding roles to grant to the user
`workspace_api_key_details`	No	Optional API key to be created for the user

Output Schema

Name	Required	Description
`ok`	Yes	Whether the tool call succeeded and returned structured data
`data`	No	Structured success payload when ok is true
`error`	No	Structured error payload when ok is false

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.9Oct 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed1 schema field changedv0.12.2Oct 2, 2026

changedInput schema / properties / email / pattern

Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"

Addedv1.0.1May 7, 2026
RemovedMay 1, 2026
First observedJan 1, 2026

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the non-read-only, non-destructive, non-idempotent, open-world profile; the description's real value is disclosing that workspace grants are deferred until the invitee accepts and that an API key can be provisioned inline. It says nothing about duplicate-invite behavior, whether an invite email is sent, or how pending state is represented, which are the remaining unknowns for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler, and the primary action is front-loaded. The second sentence earns its place by preventing redundant workspace calls, though the optional/required wording costs a little precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the core action, the bundled provisioning, and the deferred-effect caveat; an output schema exists so return values need no explanation, and annotations cover the safety profile. The gap is the mismatch over whether workspace assignment is required and no mention of duplicate/pending-invite handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema carries parameter meaning and baseline 3 applies. The description adds little parameter detail and slightly conflicts with the schema by calling workspace provisioning "optional" while `workspaces` is a required parameter, which could mislead an agent skimming the prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Invite a new org user") plus the bundled side effects (workspace access, API key) and names the sibling tools that handle follow-up changes. An agent can distinguish it from add_workspace_member, resend_user_invite, and update_user without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes follow-up workspace changes to add_workspace_member or update_workspace_member, and clarifies the deferred-timing condition ("apply only after acceptance"). It does not address adjacent cases such as an already-pending invite (resend_user_invite) or existing users (update_user), so guidance is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server