Core Concepts

This page explains the building blocks of AgentBridge: MCP, providers, tools, integrations, executions, the token vault, and the full request lifecycle. Understanding these concepts will help you reason about how your agent calls propagate through the system.

MCP — Model Context Protocol #

The Model Context Protocol (MCP) is a standard for how AI agents discover and invoke external capabilities. An MCP gateway exposes a catalog of tools — named operations with defined input/output schemas — that an AI model can call to take actions in the world.

Without a gateway, every tool requires a bespoke integration: separate auth, separate request format, separate error handling. If your AI agent needs to interact with Notion, Slack, GitHub, Google Drive, and Gmail, that is five separate authentication flows, five different REST API contracts, and five different error formats to handle.

AgentBridge implements the MCP gateway pattern so your agent calls one endpoint and the gateway handles all provider-specific complexity. Key properties of the AgentBridge MCP implementation:

• A single POST /api/mcp/execute endpoint for all tool calls across all providers
• Uniform request shape: { provider, tool, params }
• Normalized response envelope: { status, data, latencyMs, executionId }
• Normalized error shape regardless of which provider errored — with raw provider error preserved in providerError
• Automatic token management, refresh, and encryption behind the scenes

Providers #

A provider is a third-party service that AgentBridge can route calls to. Each provider has a unique slug, an authentication type, a set of available tools, and a base URL that AgentBridge calls on your behalf.

You reference a provider by its slug in every execute call. See the Integrations page for the full provider catalog including upcoming providers (HubSpot, Jira, Linear, Discord).

Tools #

A tool is a named operation that a provider exposes. Tools are the atomic units your agent calls. Each tool has a name, an input schema (the parameters it accepts), and an output schema (the data structure returned).

Tools are scoped to a provider. The same conceptual operation can exist in multiple providers. You always specify the provider and tool together in the execute call:

{
  "provider": "notion",       // which service to call
  "tool":     "create_page",   // which operation within that service
  "params":   {               // tool-specific input parameters
    "parent_id": "abc123",
    "title":     "Meeting Notes"
  }
}

The complete tool catalogs for each provider are:

• Notion: create_page, search, update_page, get_page, list_pages
• Slack: send_message, list_channels, get_channel_history, upload_file
• GitHub: create_issue, list_issues, create_pr, get_repo, list_repos
• Google Drive: list_files, upload_file, download_file, create_folder, share_file
• Gmail: send_email, list_emails, get_email, search_emails, create_draft

Integrations #

An integration is the record created when a user connects their account for a specific provider. It binds your AgentBridge account to your Notion workspace, Slack team, GitHub account, Google Drive, or Gmail.

An integration stores:

• The encrypted OAuth access token (and refresh token, if applicable)
• The provider it belongs to
• Connection status: active or disconnected
• Token expiry and refresh metadata
• The timestamp when the integration was connected

Manage integrations in the Dashboard under Integrations, or programmatically via the Integrations API.

API Keys #

API keys identify a user or workspace when making server-to-server calls. They carry a scope (read, write, admin) and are passed as Bearer tokens in the Authorization header. Keys follow the format ab_live_ + 40 alphanumeric characters and are stored as SHA-256 hashes in the database — AgentBridge cannot retrieve the plaintext key after it is created.

Each plan limits the number of API keys you can create:

For full details on creating, using, rotating, and securing API keys, see the Authentication guide.

Executions #

An execution is a single call to POST /api/mcp/execute. Each execution:

• Is assigned a unique executionId (e.g. exec_01HXZ...) that can be used to look up the log entry later
• Is logged with: actor identity, provider, tool name, timestamp, end-to-end latency in milliseconds, HTTP status code, and result status (success or error)
• Is inspectable in the Dashboard under Logs or programmatically via GET /logs/:id
• Counts toward your plan's monthly API call quota

Execution logs do not store raw parameter values in plaintext — only the provider, tool, status, and timing are stored in searchable metadata. Full error detail from the provider is captured in a separate encrypted record when the execution fails, accessible only to the account owner.

Token Vault #

The token vault is AgentBridge's encrypted credential store. When you connect an integration, the OAuth tokens are immediately encrypted with AES-256-GCM and stored in the vault. The encryption key is stored separately from the database as an environment secret.

The vault operates in five stages during a tool execution:

1. Retrieve encrypted token

   AgentBridge looks up the encrypted token for the requested provider and user from the database.

2. Decrypt in memory

   The token is decrypted using the vault key (AES-256-GCM with a 96-bit IV and 128-bit auth tag). The plaintext token exists only in application memory.

3. Check expiry and refresh

   If the access token is expired, AgentBridge calls the provider's token refresh endpoint using the stored refresh token, encrypts the new tokens, and updates the vault record.

4. Call the provider API

   The decrypted token is passed to the provider adapter, which formats the request and calls the upstream API (e.g. api.notion.com).

5. Discard plaintext

   Immediately after the provider call completes, the plaintext token reference is released from memory and garbage-collected. It is never written to logs, never returned in API responses, and never stored unencrypted.

Request Lifecycle #

Here is the complete lifecycle of a single tool execution, from your agent's HTTP call to the JSON response:

  Client (AI Agent / SDK / curl)
       |
       |  POST /api/mcp/execute
       |  Authorization: Bearer ab_live_xxxx
       |  { provider: "notion", tool: "create_page", params: {...} }
       |
       v
  +-----------------------+
  |  API Gateway (HTTPS)  |  TLS termination, HSTS
  +-----------------------+
       |
       v
  +-----------------------+
  |  Auth Middleware       |  Validate API key (SHA-256 hash lookup)
  |                       |  Check scope: write required for execute
  |                       |  Attach user context to request
  +-----------------------+
       |
       v
  +-----------------------+
  |  Rate Limiter         |  Sliding window check (per-key + per-account)
  |                       |  Set X-RateLimit-* headers
  +-----------------------+
       |
       v
  +-----------------------+
  |  MCP Router           |  Look up Integration for provider="notion"
  |                       |  Return 400 if not connected
  +-----------------------+
       |
       v
  +-----------------------+
  |  Token Vault          |  Decrypt OAuth token (AES-256-GCM)
  |                       |  Refresh if expired
  +-----------------------+
       |
       v
  +-----------------------+
  |  Provider Adapter     |  Format request for api.notion.com
  |  (Notion)             |  Attach decrypted Bearer token
  |                       |  Call upstream API
  +-----------------------+
       |
       v
  +-----------------------+
  |  Response Normalizer  |  Map provider response to standard envelope
  |                       |  { status, data, latencyMs, executionId }
  +-----------------------+
       |
       v
  +-----------------------+
  |  Execution Logger     |  Log: actor, provider, tool, latency, status
  |                       |  Assign executionId
  +-----------------------+
       |
       v
  Client receives JSON response

Glossary #