This guide is for AuthPI account administrators using AuthPI’s hosted MCP server to inspect and configure the issuers they manage. Connect an MCP application to discover your accounts by name, list their issuers, and inspect issuer configuration and the clients, organizations, users, and agents inside them with your AuthPI account permissions.

To build an MCP integration for your application and its users, follow Secure your MCP server with AuthPI. That guide uses your AuthPI issuer and your MCP server. Calling another API through token exchange is an optional next step.

The hosted administration service at https://mcp.authpi.com/mcp uses AuthPI’s own sign-in issuer. AuthPI operates its backend exchange client and secret. Connecting to it requires no exchange-client setup in the issuers you manage.

Connect and grant read access

1. Add https://mcp.authpi.com/mcp as a remote server in an MCP application that supports streamable HTTP and OAuth. Use the exact /mcp URL.
2. Let the application discover the server’s authorization metadata and complete AuthPI sign-in and consent. The consumer needs a registered OAuth client or support for issuer-enabled Client ID Metadata Documents (CIMD); AuthPI does not provide Dynamic Client Registration (RFC 7591).
3. Request and consent to openid issuers:read to discover accounts and use the issuer tools. For resources inside an issuer, also approve the matching read scopes below. Your account membership must authorize each requested scope.
4. Call whoami to verify the signed-in user and granted OAuth scopes, then list_accounts to discover the accounts you can inspect.

The application obtains an access token for the MCP resource through authorization code with PKCE. You do not paste an AuthPI organization API key or your customer issuer’s token into this connection. The resource advertises the issuer and supported scopes through its protected-resource metadata.

If an existing connection only granted openid, authorize the connection again with issuers:read. A membership’s permissions cannot add a scope that you did not consent to. whoami remains available with openid alone.

The additional inspection scopes are:

Tools	Required OAuth and account permission scope
list_clients, get_client	issuers.clients:read
list_organizations, get_organization	issuers.organizations:read
list_users, get_user	issuers.users:read
list_agents, get_agent	issuers.agents:read

Existing openid issuers:read connections keep working for account and issuer discovery. Reauthorize to add the scopes for the new tools you want to use. Each inspection call exchanges only its own scope; once you know the account and issuer IDs, it does not additionally require issuers:read. Account discovery still tests issuer-read access, so its results do not guarantee access to every resource type.

Choose and switch accounts

The hierarchy is AuthPI account → issuer → application organization. Each AuthPI account has a backing organization in AuthPI’s own sign-in issuer. That organization is separate from the organizations your application creates inside the issuers you manage. The account_org_id argument selects the account’s backing organization; organization_id on get_organization instead identifies an application organization inside the specified issuer_id.

Ask your assistant to use an account by name, such as “Show the issuers in Acme.” It should call list_accounts, resolve the name to a returned account, and pass that account’s account_org_id to issuer tools. It should finish discovery before treating a name as unique, or ask you to choose an explicit account ID if discovery is incomplete. If names are missing or ambiguous, it should show the account IDs and ask you to choose before continuing. Account and issuer names help you choose; IDs determine which resource a tool reads.

Call list_accounts with {} for the first page. Its accounts entries contain account_id, account_org_id, and account_name (which is null for an unnamed account). The tool checks up to five membership candidates per call and returns only verified accounts where you can currently delegate issuers:read. It does not return billing details or account settings.

When has_more is true, call list_accounts again with the returned next_cursor as cursor. You may set limit to an integer from 1 to 5; it defaults to 5 and bounds the memberships checked, so the number of returned accounts can be smaller. unavailable_count counts memberships on that page that could not authorize issuer reads or resolve to a matching account. An empty accounts array with has_more: true still has another page. This is a discovery list for these read tools, not a complete account inventory.

If whoami includes selected_organization_id, the connection is restricted to that account organization. You may omit account_org_id; passing it explicitly must select that same organization. To change to another account, authorize a connection for that account. Without a token selection, pass account_org_id explicitly even when only one account is returned. The server never picks the first account for you.

list_accounts also respects that token selection and only checks the selected account. Otherwise, its candidates come from the membership snapshot returned by whoami. Newly granted memberships may require reconnecting to appear. Account discovery and inspection calls check current user and membership authority through a fresh delegated token; a successful earlier call does not preserve access after removal.

For a connection that permits multiple accounts, the assistant can switch accounts by passing another returned account_org_id on the next tool call. It should keep that choice within the conversation, discard the previous issuer selection and pagination cursors when changing accounts, and list issuers in the newly chosen account. The MCP server has no global “current account”; each call carries its selection, and the conversation’s preference never grants permissions.

Inspect issuers

Ask your MCP application to call list_issuers with the account you selected. For example, replace the example account_org_id with the value from list_accounts:

{
  "account_org_id": "org_0000000000000000000000001",
  "limit": 20
}

The result contains an issuers array of summaries and has_more. When has_more is true, pass the returned next_cursor as cursor on the next list_issuers call, keeping the same account_org_id. limit is an integer from 1 to 100 and defaults to 50. A positive invalid_count, when present, means Core skipped issuer records it could not safely load; do not treat that page as a complete inventory.

To inspect an issuer from the result, call get_issuer with its id and the same account selection. Replace both example IDs below:

{
  "account_org_id": "org_0000000000000000000000001",
  "issuer_id": "i_0123456789abcd"
}

The result contains an issuer object with its configuration, including settings and available scopes. Secrets for authentication providers are excluded.

Both issuer tools return context with the verified account_id, account_org_id, and account_name; get_issuer also includes context.issuer_id. The assistant should use this context to label results with the account and issuer it actually read.

Tool	Inputs	Result
whoami	None	Verified user and OAuth client, oauth_scopes, organization membership snapshots, and selected_organization_id when present.
list_accounts	Optional cursor and limit (1–5).	Verified account IDs and names in accounts, plus has_more, optional next_cursor, and unavailable_count.
list_issuers	account_org_id selection, optional cursor and limit (1–100).	Account context, issuers summaries with IDs, status, timestamps, counts of authentication methods, access mode, branding status, and readiness; pagination fields as described above.
get_issuer	account_org_id selection and required issuer_id.	Account and issuer context, plus issuer: the configuration for that account’s issuer.

These tools are read-only. They do not create issuers or modify configuration. All tools advertise an outputSchema derived from AuthPI’s shared schemas through MCP tools/list. Successful results include structuredContent and matching JSON text; tool errors use isError: true and are outside the success schema.

Inspect resources inside an issuer

Select an issuer from the chosen account, then call any of list_clients, list_organizations, list_users, or list_agents with these arguments, replacing the example IDs:

{
  "account_org_id": "org_0000000000000000000000001",
  "issuer_id": "i_0123456789abcd",
  "limit": 20
}

Each response includes account and issuer context, an array named after the collection, and has_more, with optional next_cursor and invalid_count. Pass next_cursor as cursor to continue the same collection in the same account and issuer. Limits are 1–100, default 50, except list_agents, which accepts 1–20 and defaults to 20. When switching accounts or issuers, discard previous resource selections and cursors. A positive invalid_count means Core skipped records; the page is not a complete inventory.

Use the matching detail tool with the same account and issuer and the resource ID:

Tool	Additional required argument	Detail returned
get_client	client_id from a client’s id	Client identity, status, confidentiality, and settings including scopes, redirect URIs, grants, and configured token-exchange policy. No client secret or metadata.
get_organization	organization_id from an organization’s id	Application organization identity, status, scopes, invitation settings, member limits, and available counts. No SSO credentials, contact details, or metadata.
get_user	user_id from a user summary’s user_id	User identity, username, status, scopes, and timestamps. No profile, security material, or metadata.
get_agent	agent_id from an agent’s id	Agent identity, name, description, model/provider/version when available, status, scopes, and timestamps. No verifiers or metadata.

Detail responses use the singular key (client, organization, user, or agent) alongside account and issuer context. These tools inspect resources belonging to your customer issuer. They do not change the MCP connection’s account selection or operate as that application’s users or agents.

User collections are ordered by user ID and return index summaries with user_id, issuer_id, username_type, status, and timestamps. They do not contain plaintext usernames; use get_user for one user’s username. Internal hashes and storage routing fields are excluded. Client and organization collections return compact configuration summaries; agent collections return identity, name, model/provider/version, status, and timestamps. Use get_agent for its description and scopes. All eight inspection tools are read-only.

Create a development application and update settings

The hosted MCP also exposes create_issuer, create_client, update_issuer, and update_client. Write access must be enabled by the hosted service operator and separately granted through OAuth consent and your AuthPI account membership. A read-only connection cannot perform writes. Initial authentication challenges continue to request read scopes; an attempted write without consent challenges for that tool’s write scope.

Tools	Required OAuth and account permission scope
create_issuer, update_issuer	issuers:write
create_client, update_client	issuers.clients:write

These are AuthPI administration permissions. Scopes configured inside your issuer or client describe your own application’s access; they do not grant access to AuthPI’s administration API.

Ask your assistant to select an account, inspect existing configuration, and describe the target and intended changes before an authorized write. Every mutation requires an explicit account_org_id, even when the connection already selects an account. Issuers have no enforced development/production flag: use a clearly named development issuer and verify its ID before modifying settings. The tools can update existing issuers, so the name alone is not a safety boundary.

To create a development issuer, replace the account ID and generate a new UUID for idempotency_key:

{
  "account_org_id": "org_0000000000000000000000001",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "issuer": {
    "name": "My app — development",
    "available_scopes": ["openid", "profile", "email"]
  }
}

create_issuer accepts a name, optional description, and available scopes. Core supplies the default issuer settings, including password authentication. Reuse a suitable existing issuer instead when that matches your intended user pool.

Call create_client with the returned issuer ID and a different idempotency UUID:

{
  "account_org_id": "org_0000000000000000000000001",
  "issuer_id": "i_0123456789abcd",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440001",
  "client": {
    "name": "Development web app",
    "application_type": "spa",
    "redirect_uris": ["http://localhost:3000/callback"],
    "scopes": ["openid", "profile", "email"]
  }
}

Client creation supports public spa and native applications with authorization-code PKCE and refresh-token grants. It accepts optional description, post-logout callbacks, and allowed resources. It does not create confidential clients or return client secrets. Use the resulting client ID and your issuer URL with the relevant SDK or quickstart, then verify a real login in your application.

For a creation retry after a timeout, reuse the same idempotency key and identical inputs. Core retains idempotency records for 24 hours; do not assume retries remain deduplicated after that window. See Idempotency.

Update configuration while debugging

Read get_issuer or get_client first. Its result includes etag; pass that exact quoted value as the update tool’s required if_match. Replace the example version below with the value you actually read. For example, update_client can correct a callback URL:

{
  "account_org_id": "org_0000000000000000000000001",
  "issuer_id": "i_0123456789abcd",
  "client_id": "c_0000000000000000000000001",
  "if_match": "\"1700000000000\"",
  "patch": {
    "settings": {
      "openid": {
        "redirect_uris": ["http://localhost:3001/callback"]
      }
    }
  }
}

• update_issuer accepts name, description, available scopes, signup/session settings, and OpenID policy fields for refresh-token enablement, redirect guardrails, scope descriptions/presentation, CIMD, and resource indicators.
• update_client accepts name, description, logo, scopes, session settings, organization restrictions, and OIDC callbacks, resources/audiences, signing algorithm, and token lifetimes.

Send only the fields you intend to change. Redirect-policy updates preserve omitted fields and validate the resulting policy before saving. Arrays and scope-description/presentation maps replace their existing value; preserve entries you still need. The tools exclude resource status/deletion, metadata, authentication-method edits, secrets, and client grant/type or token-exchange policy changes. Core also refuses ordinary write authority on an existing privileged token-exchange client.

Successful mutations return the resource and verified account/issuer context, with the same public projection as the corresponding read tool. Read the configuration again to verify the change. If another edit occurred since your read, the update returns precondition_failed: reread, reconsider the patch, and use the new version only after reviewing the current state. Wildcard and weak ETags are rejected. See Conditional requests.

Resolve a failed call

A call to list_accounts, list_issuers, or get_issuer without issuers:read returns HTTP 403 with insufficient_scope. The WWW-Authenticate challenge names openid issuers:read so the application can request fresh consent. A resource inspection tool similarly challenges for openid plus its own required scope, such as issuers.clients:read. This does not prevent whoami calls with openid.

Failures during tool execution return an MCP result with isError: true. Its text contains error, message, and an error_id you can share with AuthPI support.

Error	What to do
organization_required	Choose an account from list_accounts and pass its account_org_id.
organization_mismatch	Use the token’s selected account organization, or reconnect to select another account.
organization_forbidden	Reconnect and check account access; the requested account organization is absent from this token.
delegation_denied or access_denied	Check your current account membership and the scope required by the tool, then reconnect.
account_unavailable	Check that the selected organization has an accessible AuthPI account.
not_found	Use IDs from the matching list tool in the same account and issuer.
invalid_request	Check the supplied fields, resource IDs, and pagination cursor against the tool schema.
payment_required	Resolve billing requirements for the selected account before retrying.
precondition_failed	Reread the issuer/client and review concurrent changes before retrying with its new etag.
conflict	A creation with this key is still processing; retry later with the same key and identical input.
idempotency_mismatch	Restore the input originally used with that creation key, or use a new key for a distinct creation.
mutation_outcome_unknown	The write may have succeeded. Retry creation with its original key and input; reread before retrying an update.
invalid_cursor	Restart list_accounts without a cursor; membership changes or a new connection can invalidate an earlier discovery cursor.
reauthorization_required	Reconnect and retry with a fresh grant.
delegation_unavailable	Retry later; contact AuthPI support if it persists. Customers do not configure the hosted service’s exchange client.
upstream_unavailable or tool_error	Retry later; include error_id when reporting a persistent failure.

How delegation works

For each resource call, AuthPI MCP exchanges your MCP access token for a delegated Core API token restricted to the selected account organization and the one read or write scope required by that tool. Account discovery requests issuers:read and performs this exchange separately for each membership candidate it checks. The MCP resource is https://mcp.authpi.com/mcp; the Core resource is https://api.authpi.com. The human remains the subject of the delegated token, and AuthPI’s service client is its actor. The original MCP token is not forwarded to Core.

The tool verifies that the selected organization has the matching AuthPI account before reading resources. Core also verifies that the issuer belongs to that account, and inspection results must match the requested issuer and resource ID. Neither the delegated token nor the exchange client secret is returned in tool results. See the token-exchange reference for the issuer’s scope, membership, and lifetime rules.

Core trusts AuthPI’s own configured issuer. An exchange policy in your issuer does not make its output a valid AuthPI Core credential, even if you set the target resource to the Core URL. Customer issuers can issue delegated tokens for APIs that explicitly trust them.

Core requires a delegated profile for its canonical resource audience. The existing AuthPI Console retains a separate legacy-audience compatibility path; that exception does not extend trust to customer issuers. For ordinary backend automation that manages AuthPI resources, use an organization API key.