Skip to main content
Profile exposes a Model Context Protocol server that lets AI agents (ChatGPT Apps, Claude Connectors, or any MCP-compatible client) act on behalf of a Profile user. An authorized agent can send assessment invites, manage tags, and retrieve behavioral summaries through the same backend that powers the Profile web app. This page is a human-readable overview of that surface. The authoritative, always-current catalog is what the MCP server itself reports in response to a tools/list call. If you need exact JSON schemas for a code generator, ask the server.

​
How it connects

  • Endpoint: POST https://vanguard.profilebehavior.com/mcp (streamable HTTP transport)
  • Discovery: GET /.well-known/oauth-protected-resource returns the authorization server URL and supported scopes
  • Authentication: OAuth 2.1 (authorization code + PKCE). See the Authentication page for the full flow.
When an MCP client hits /mcp without a token, the response includes a WWW-Authenticate: Bearer resource_metadata="..." header pointing at the protected-resource metadata. Spec-compliant clients follow this automatically and initiate the OAuth flow. Tokens issued through this flow are scoped to one Profile account: the account the user was signed into when they consented. An agent connected to Account A cannot read or modify data in Account B, even if the same user belongs to both.

​
Tool surface

Tools operate on the account the user consented from. Tool inputs take resource-specific IDs (tag IDs, profile IDs) but never an account ID. Every tool advertises title, description, and behavior annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so the client can decide when to prompt for confirmation.

​
Tags

Required scope: tags:manage

​
list_tags

Read-only. Returns tags on the connected account with optional paginated listing and full-text search over the tag label.
  • Inputs: search (optional string), limit (optional number), page (optional 1-indexed number)
  • Returns: array of { id, label, color, profiles } plus a total count
  • Side effects: none
  • Typical errors: no required input is missing, so most failures are infrastructure-level and return a generic message.

​
create_tag

Additive write. Creates a new tag on the connected account.
  • Inputs: label (string, required), color (string, required, one of emerald, red, yellow, orange, blue, indigo, purple, pink, zinc)
  • Returns: the created tag
  • Side effects: writes an audit-log entry
  • Typical errors: label is required; invalid color "x"

​
update_tag

Destructive write (overwrites label and color). Idempotent.
  • Inputs: tagId (string, required), label (string, required), color (string, required, same allowed values as create)
  • Returns: the updated tag
  • Side effects: writes an audit-log entry; invalidates cached views of the tag
  • Typical errors: Tag not found (also returned when the tag exists but belongs to a different account); validation errors on label and color

​
delete_tag

Destructive write. Idempotent on subsequent calls (the tag is simply not found).
  • Inputs: tagId (string, required)
  • Returns: { deleted: true, tagId }
  • Side effects: removes the tag from every profile it was attached to; writes an audit-log entry
  • Typical errors: Tag not found

​
assign_tags_to_profiles

Destructive write (replaces the profile set on the tag). Idempotent.
  • Inputs: tagId (string, required), profileIds (array of strings, required, can be empty to clear all assignments)
  • Returns: the updated tag with its new profile set
  • Side effects: writes an audit-log entry
  • Typical errors: Tag not found; One or more profiles not found on this account when any supplied profile ID doesn’t exist on the connected account

​
Profiles

Required scope: profiles:read

​
list_profiles

Read-only. Returns profiles the user has access to on the connected account.
  • Inputs: search (optional string, full-text over name), tagId (optional string, filter by tag membership), isCompleted (optional boolean, filter by assessment completion), limit (optional number), page (optional 1-indexed number)
  • Returns: array of profile summaries { id, name, email, phone, isCompleted, tagIds } plus a total count
  • Side effects: none
  • Typical errors: invalid tagId if a malformed tag ID is supplied

​
Assessment invites

Required scope: profiles:write

​
send_assessment_invite

Additive write. Sends a real assessment invite email or SMS to the recipient.
  • Inputs: email (optional string, but required if no phone), phone (optional string, E.164 format, required if no email), tagId (optional string to attach the new profile to a tag), customId (optional string for external ID mapping)
  • Returns: { profileId, created, email, phone }. created: true means a new profile was created; created: false means the recipient already had a profile and the invite was added or re-sent.
  • Side effects: sends a magic link via email or SMS; creates or updates a Profile record; writes an audit-log entry
  • Typical errors: Email or phone number is required; One or more tags not found for account; Maximum reports reached for trial account (402 for trial accounts at their profile cap)

​
Behavioral summary

Required scope: profiles:read

​
get_behavioral_summary

Composite read of a profile’s behavioral data. Triggers debrief generation on first access.
  • Inputs: profileId (string, required)
  • Returns: profile identity (name, email, isCompleted), DISC scores and style, Focus trait scores and levels, Core value rankings, and the AI-generated debrief content plus its ID. debriefGenerated: true indicates a new debrief was created during this call.
  • Side effects: if no debrief exists for the profile, one is generated and stored. Generation can take up to a minute and consumes AI compute on our side.
  • Typical errors: Profile not found; Profile is not on this account (when the profile exists but belongs to a different account)

​
Why this tool is marked non-read-only

The MCP annotation for get_behavioral_summary has readOnlyHint: false because first-time calls for a given profile write a new AIReportFixture to the database. Subsequent calls for the same profile read the cached result. Clients may prompt for confirmation on first access; repeated calls do not re-prompt if the grant permits.

​
Scopes

MCP tool calls use a subset of the full OAuth scope set. The complete list is in the Authentication page.
ScopeUsed by tools
profiles:readlist_profiles, get_behavioral_summary
profiles:writesend_assessment_invite
tags:managelist_tags, create_tag, update_tag, delete_tag, assign_tags_to_profiles
Scopes the user doesn’t grant at consent time block the corresponding tools entirely. An LLM calling create_tag without tags:manage receives an error, never a silent success.

​
Connecting from a client

​
ChatGPT Apps

Register a new app in the OpenAI Apps SDK dashboard. Point the MCP server URL at https://vanguard.profilebehavior.com/mcp. OpenAI’s platform handles OAuth discovery and Dynamic Client Registration against the authorization server referenced in our protected-resource metadata.

​
Claude Connectors

In Claude’s connector settings, add a custom MCP server with URL https://vanguard.profilebehavior.com/mcp. Claude follows the same discovery path.

​
Custom MCP clients

If you’re writing a client directly against the MCP spec (e.g. using @modelcontextprotocol/sdk), the only Profile-specific configuration is the server URL. Everything else (DCR, authorization, token exchange, tool invocation) is standard MCP + OAuth 2.1.

​
Inspecting the live tool catalog

If you need to see the tool list with exact JSON schemas, either connect with mcp-inspector (authenticates via OAuth, lets you list tools and invoke them by hand) or have a registered MCP client send a standard tools/list request. This is always more current than any documentation page, including this one.