Skip to main content

Agent Personas

Create unified MCP endpoints that aggregate selected tools from multiple MCP servers into a single, cohesive interface. Agent Personas enable you to build purpose-built AI agents with curated toolsets and flexible authentication options for both human users and automated systems.

Overview​

An Agent Persona acts as a proxy layer that:

  • Aggregates tools from multiple downstream MCP servers into one endpoint
  • Provides unified authentication for accessing all underlying services
  • Routes tool calls automatically to the appropriate MCP server
  • Manages sessions across multiple gateway connections

This architecture simplifies AI client configuration by replacing multiple MCP server connections with a single Agent Persona endpoint.

Key Features​

Tool Aggregation​

Select specific tools from any number of MCP servers in your organization. Tools are automatically prefixed with their source gateway name to prevent naming conflicts (e.g., Slack_searchMessages, Jira_createJiraIssue).

Flexible Authentication​

Agent Personas support three authentication modes to accommodate different use cases:

Auth ModeUse CaseUser Type
InteractiveBrowser-based SSO loginHuman users
Non-InteractiveBearer token for automationService accounts
PassthroughCustom headers with optional JWTExternal systems

Session Management​

Persona sessions are automatically managed with 30-minute TTL. Sessions are reused across requests to the same persona-gateway combination for optimal performance.

Real-time Status Tracking​

Monitor connection status for each user and gateway combination to ensure all required OAuth connections are established.

Use Cases​

Mini Me (Personal Agents)​

Create a personalized agent that acts on behalf of a specific user. The agent inherits the user's identity and permissions across all connected services.

Example: Developer Productivity Agent

An agent with access to:

  • GitLab for merge request management, code review, and pipeline monitoring
  • Jira for issue tracking, sprint management, and ticket updates
  • Slack for team communication, searching conversations, and posting updates
  • Confluence for documentation access and page creation

With this persona, you can ask your AI assistant:

  • "Search for all open merge requests assigned to me in GitLab"
  • "Create a Jira issue for the bug we discussed in Slack #engineering channel"
  • "Find the onboarding documentation in Confluence and summarize it"
  • "Post a deployment notification to #releases channel in Slack"

When the agent performs actions, they appear as if the user performed them directly.

Machine-to-Machine (Automated Workflows)​

Create service account-based agents for CI/CD pipelines, scheduled jobs, or backend automation that don't require human interaction.

Example: DevOps Automation Agent

An agent configured for automated workflows:

  • GitLab for merge request approvals and pipeline triggers
  • Jira for automatic ticket transitions on deployment
  • Slack for deployment notifications and alerts
  • Confluence for auto-updating release documentation

Example automated workflows:

  • When a pipeline succeeds, transition the linked Jira issue to "Done" and notify Slack
  • Post daily standup summaries aggregating GitLab commits and Jira progress
  • Create release notes in Confluence from merged MR descriptions

What You Can Do with Agent Personas​

The persona aggregates tools from multiple services, enabling AI agents to perform complex cross-platform operations:

Development & DevOps​

  • Code Review Automation

    • "Get the changes from MR #123 in GitLab and summarize the code modifications"
    • "List all commits from the past week and create a changelog"
    • "Check pipeline status for the main branch"

  • Issue Management

    • "Create a Jira bug for the error we found, assign it to the backend team"
    • "Search for all high-priority issues in the current sprint"
    • "Update the story points on PROJ-456"

Communication & Collaboration​

  • Team Coordination

    • "Search Slack for messages about the API redesign from last week"
    • "Post the sprint review summary to #engineering channel"
    • "Find all unread messages in my DMs"

  • Documentation

    • "Get the architecture decision record from Confluence"
    • "Update the API documentation page with the new endpoints"
    • "Search for all pages mentioning authentication"

Cross-Platform Operations​

  • Integrated Workflows
    • "Find the Jira ticket mentioned in the latest Slack thread about login issues"
    • "Create a Confluence page summarizing all MRs merged this release"
    • "Post the Jira sprint burndown to Slack every morning"

Creating an Agent Persona​

Prerequisites​

  • Access to Cequence AI Gateway with App User or higher permissions
  • At least one deployed MCP server with available tools
  • Completed OAuth authentication for any services you want to include

Step 1: Navigate to Agent Personas​

  1. Log in to the Cequence AI Gateway portal
  2. Click Agent Personas in the left navigation
  3. Click Create Agent Persona

Step 2: Configure Basic Information​

  1. Enter a Name for your persona (required)
  2. Add a Description to help others understand the persona's purpose (optional)
  3. Click Next

Step 3: Select Tools​

  1. Browse the list of available MCP servers (gateways)
  2. Expand each gateway to view its available tools
  3. Select the checkbox next to each tool you want to include
  4. Use the search bar to find specific tools
  5. Click Next
Tool Selection

Only include tools that are necessary for your agent's purpose. This follows the principle of least privilege and simplifies the agent's interface.

Step 4: Configure Authentication​

Select one or more authentication modes based on your use case:

Interactive Authentication (SSO)​

Best for human users accessing the agent through browser-based AI clients.

  1. Enable Interactive authentication
  2. Users will authenticate via SSO when connecting
  3. Actions are performed under the user's own identity

Non-Interactive Authentication (Bearer Token)​

Best for automated systems, CI/CD pipelines, and service accounts.

  1. Enable Non-Interactive authentication
  2. After creation, generate an API key from the persona details page
  3. Use the generated bearer token directly in your client configuration

Passthrough Authentication​

Best for systems that manage their own authentication or need to pass custom headers.

  1. Enable Passthrough authentication
  2. Optionally enable JWT Validation for additional security:
    • Provide a JWKS URL or JWKS JSON for key verification
    • Specify the expected Issuer (optional)
    • Specify the expected Audience (optional)
  3. Configure Custom Headers to pass through to downstream services

Step 5: Review and Create​

  1. Review your configuration
  2. Click Create & Deploy
  3. Your Agent Persona will be deployed and ready for use

Authentication Modes​

Interactive Flow (SSO)​

The interactive flow uses browser-based SSO authentication, ideal for AI assistants used by human operators.

How it works:

  1. User initiates connection to the Agent Persona
  2. Browser redirects to the identity provider (SSO)
  3. User authenticates with their credentials
  4. Upon success, a session is established
  5. All tool calls execute under the user's identity

Requirements:

  • Browser-based AI client (Claude Desktop, Cursor, etc.)
  • User must have valid SSO credentials
  • User must complete OAuth for each underlying service

Non-Interactive Flow (Bearer Token)​

The non-interactive flow provides a bearer token for direct API access, ideal for programmatic access and automation.

How it works:

  1. Generate an API key for the persona from the portal
  2. Copy the bearer token provided
  3. Configure your MCP client with the token in the Authorization header
  4. All requests authenticate using this token

Example MCP Client Configuration:

{
  "mcpServers": {
    "my-devops-agent": {
      "url": "https://your-gateway-endpoint.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-token-here"
      }
    }
  }
}

This configuration can be used directly in Claude Desktop, Cursor, or any MCP-compatible client.

Passthrough Flow​

The passthrough flow allows external systems to provide their own authentication, with optional JWT validation.

How it works:

  1. Client sends requests with custom headers
  2. Headers are forwarded to downstream MCP servers
  3. If JWT validation is enabled:
    • Token is validated against JWKS
    • Issuer and audience claims are verified (if configured)
    • Invalid tokens are rejected

JWT Validation Options:

OptionDescription
JWKS URLURL to fetch JSON Web Key Set for token validation
JWKS JSONInline JSON Web Key Set (alternative to URL)
IssuerExpected token issuer claim (optional)
AudienceExpected token audience claim (optional)

Custom Headers:

Configure headers that should be passed through to downstream services:

Header NameValuePurpose
X-Api-KeyAPI key valueService authentication
X-Tenant-IdTenant identifierMulti-tenant routing

Managing API Keys​

API keys enable non-interactive authentication for automated workflows.

Generating an API Key​

  1. Navigate to your Agent Persona's detail page
  2. Click the API Keys tab
  3. Click Generate API Key
  4. Configure the key:
    • Name: Descriptive name for the key
    • Expiration: Never, 30 days, 90 days, or 1 year
  5. Click Generate
  6. Copy and securely store the bearer token (it won't be shown again)

Key Expiration Options​

OptionDurationUse Case
NeverNo expirationLong-running services (rotate manually)
30 daysShort-termTemporary integrations, testing
90 daysMedium-termProject-based automation
1 yearLong-termProduction services

Revoking an API Key​

  1. Navigate to the API Keys tab
  2. Click the three-dot menu next to the key
  3. Select Revoke
  4. Confirm the revocation
caution

Revoking a key immediately invalidates it. Ensure no active systems depend on the key before revoking.

Completing OAuth Connections​

For Agent Personas using the interactive flow, users need to complete OAuth authentication for each underlying MCP server.

Checking Connection Status​

  1. Navigate to your Agent Persona's detail page
  2. View the Authentication Checklist in the Overview tab
  3. Each gateway shows its connection status:
    • Connected: OAuth is complete
    • Not Connected: OAuth required

Completing OAuth Connections​

  1. Click Connect next to a disconnected gateway
  2. Complete the OAuth flow in the popup window
  3. Upon success, the status updates to Connected

Re-authenticating​

If a connection expires or is revoked:

  1. Click the Re-authenticate button
  2. Complete the OAuth flow again
  3. New credentials are stored automatically

Connecting AI Clients​

Using the MCP Endpoint​

Your Agent Persona provides a single MCP endpoint URL, visible on the persona details page.

Claude Desktop Configuration​

Add the persona to your Claude Desktop claude_desktop_config.json:

For Interactive (SSO) Authentication:

{
  "mcpServers": {
    "my-agent-persona": {
      "command": "npx",
      "args": [
        "-y",
        "@cequence-ai/mcp-remote",
        "https://your-persona-endpoint.a.run.app/mcp"
      ]
    }
  }
}

For Non-Interactive (Bearer Token) Authentication:

{
  "mcpServers": {
    "my-agent-persona": {
      "url": "https://your-persona-endpoint.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-token-here"
      }
    }
  }
}

Cursor Configuration​

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "my-agent-persona": {
      "url": "https://your-persona-endpoint.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-token-here"
      }
    }
  }
}

For more details on client configuration, see:

Best Practices​

Security​

  • Use least privilege: Only include tools necessary for the agent's purpose
  • Rotate API keys: Set expiration dates and rotate keys periodically
  • Enable JWT validation: For passthrough flows, validate tokens when possible
  • Audit connections: Regularly review which users have connected OAuth

Organization​

  • Use descriptive names: Name personas clearly (e.g., "DevOps Automation Agent")
  • Document purposes: Add descriptions explaining what each persona is for
  • Group by function: Create separate personas for different workflows

Performance​

  • Minimize tool count: Large tool sets increase response latency
  • Monitor connection status: Ensure OAuth connections remain valid
  • Use appropriate auth mode: Choose non-interactive for automation to avoid session timeouts

Troubleshooting​

Connection Errors​

Issue: "Downstream gateway endpoint not available"

Solution: The underlying MCP server may be unavailable. Check:

  1. MCP server status in the MCP Servers page
  2. Network connectivity to the downstream service
  3. Service account credentials are valid

Authentication Failures​

Issue: "Invalid or expired token"

Solution:

  1. For API keys: Generate a new key and update your client configuration
  2. For interactive: Re-authenticate via the portal
  3. For passthrough: Verify JWT is properly signed and not expired

Missing Tools​

Issue: Expected tools not appearing in the persona

Solution:

  1. Verify tools are enabled in the underlying MCP server
  2. Check that OAuth is complete for the gateway
  3. Confirm tools were selected during persona creation

OAuth Errors​

Issue: "OAuth connection failed"

Solution:

  1. Verify OAuth credentials in the underlying MCP server
  2. Check redirect URIs are correctly configured
  3. Ensure required scopes are approved

Getting Help​

If you encounter issues not covered in this documentation:

  • Support: Contact your organization's administrator
  • Community: Reach out to Cequence support