# Char Documentation

> Char lets you embed AI agents into your web applications with WebMCP-powered tools and SSO-first authentication.

## Quick Start

Let Claude Code handle the setup:

```bash
# Install Char plugin (auto-adds MCP servers)
/plugin marketplace add WebMCP-org/char-plugin
/plugin install char@webmcp
```

Chrome DevTools MCP fork source:
https://github.com/WebMCP-org/npm-packages/tree/main/packages/chrome-devtools-mcp

Then run `/char:setup` or tell Claude: "Set up Char in my app"

## Char SaaS MCP

The Char SaaS MCP (`https://app.usechar.ai/mcp`) connects Claude Code to your Char account.

**First-time setup**: When you first use a tool, a browser window opens. Sign in (or create an account), name your organization, click "Authorize"—done. No dashboard, no copying values. This only happens once; Claude Code remembers your session.

**What you can do**:
- Configure SSO without visiting a dashboard
- Manage your organization (members, plan, usage)
- Access browser tools from WebMCP tabs
- Check subscription status and billing

**Available tools**:

| Tool | Purpose |
|------|---------|
| `get_profile` | Your user profile and org memberships |
| `list_organizations` | Organizations you belong to |
| `get_organization` | Organization details by ID or slug |
| `list_members` | Members in current organization |
| `manage_idp_config` | Configure SSO settings |
| `test_idp_connection` | Test IDP connectivity |
| `list_plans` | Available plan tiers |
| `get_plan_info` | Current plan, features, and usage |
| `check_feature` | Check feature accessibility |
| `get_subscription` | Subscription status |
| `get_billing_url` | Checkout or customer portal URL |
| `hub_list_tools` | Browser tools from WebMCP tabs |
| `hub_list_sources` | Active browser sources |
| `hub_call_tool` | Execute a browser tool |

## Why Char?

**Cross-App Tool Access**: Tools registered in one application are available to agents in every other application—all scoped to the authenticated user. This enables cross-site RPC that was previously impossible without building custom integrations.

**AI-Tested Tools**: The AI that writes your tools also tests them. Chrome DevTools MCP lets Claude Code call the exact same WebMCP tools that your embedded agent uses. If Claude can't use a tool, it fixes it—before your users ever see it.

## Documentation Structure (Diátaxis Framework)

This documentation follows the [Diátaxis framework](https://diataxis.fr/).

### How-to Guides (Task-oriented)

#### Claude Code Setup
- [Install MCP Servers](/guides/mcp-servers): Chrome DevTools MCP and docs server
- [Set Up Char with Claude Code](/guides/claude-code-setup): Run the setup skill

#### Manual Setup
- [Quickstart](/quickstart): Embed Char manually
- [Embedding the Agent](/guides/embedding-agent): Framework integration (React, Vue, etc.)

#### Customize
- [Add Custom Tools](/guides/webmcp-tools): WebMCP tool registration
- [Creating Skills](/guides/creating-skills): Write SKILL.md files
- [Custom Styling](/guides/custom-styling): Theme the agent

#### Identity Providers
- [Identity Providers Overview](/identity-providers/index): Configure SSO
  - [Okta](/identity-providers/okta)
  - [Azure AD](/identity-providers/azure-ad)
  - [Auth0](/identity-providers/auth0)
  - [Google](/identity-providers/google)
  - [WorkOS](/identity-providers/workos)
  - [AWS Cognito](/identity-providers/aws-cognito)
  - [Firebase](/identity-providers/firebase)
  - [Clerk](/identity-providers/clerk)
  - [Keycloak](/identity-providers/keycloak)
  - [OneLogin](/identity-providers/onelogin)
  - [Ping Identity](/identity-providers/ping-identity)
  - [Custom OIDC](/identity-providers/custom-oidc)

### Explanation (Understanding-oriented)

#### Architecture
- [How Char Works](/explanation/how-char-works): Architecture overview
- [Tool Hub](/explanation/tool-hub): The identity-scoped hub that aggregates tools
- [Cross-App Tools](/explanation/cross-app-tools): How tools work across applications
- [Session Inheritance](/explanation/session-inheritance): Why no new OAuth flows are required

#### Development
- [AI-Tested Tools](/explanation/ai-tested-tools): Why the development workflow matters
- [Organization Skills](/explanation/skills): Why skills exist and how they work
- [Deployment Tiers](/explanation/deployment-tiers): Progressive adoption from Tier 0 to Tier 2

#### Security
- [Security Architecture](/explanation/security-architecture): Overall security design
- [Context Isolation](/explanation/context-isolation): Security model and prompt injection defense
- [Trust Boundaries](/explanation/trust-boundaries): Internal vs external tool trust
- [Federated Authentication](/explanation/federated-auth): Why IDP-delegated auth is more secure

### Reference (Information-oriented)
- [API Reference](/api-reference/overview): REST API overview (auto-generated from OpenAPI)
- [OpenAPI Spec](https://app.usechar.ai/api/spec.json): Live OpenAPI 3.1 specification
- [Authentication](/authentication): Bearer tokens and authorization
- [Error Codes](/api-reference/errors): API error reference
- [Agent Attributes](/reference/agent-attributes): All char-agent attributes
- [CSS Variables](/reference/css-variables): Complete theming reference
- [Skill Schema](/reference/skill-schema): SKILL.md format specification
- [MCP Tools](/reference/mcp-tools): Char SaaS MCP tool reference

## Core Concepts

### Tool Hub
The Tool Hub is a Cloudflare Durable Object scoped to each user within your organization. It aggregates tools from all connected sources (browser tabs, external MCP clients) into a unified registry. The agent in any application can invoke tools from any other application.

### Embedded Agent
`<char-agent>` is an iframe-based custom element that renders chat UI inside your app and connects to the user's Tool Hub for cross-app capabilities.

### WebMCP Tools
Your app registers tools using `navigator.modelContext.registerTool()`. The embedded agent calls these tools to interact with your UI. Tools are published to the Tool Hub and available across all your applications.

### Session Inheritance
The agent inherits the user's existing session. Tools execute with the user's cookies and permissions—no new OAuth flows, no service accounts, no elevated permissions.

### SSO-first Identity
Char validates JWTs from your identity provider using public key cryptography (JWKS). No shared secrets, no credential storage. Your IDP is the single source of truth.

### Deployment Tiers
- **Tier 0**: Key-only embed (`publishable-key`) with org-scoped access
- **Tier 1**: Key + ID token (`connect({ publishableKey, idToken })`) for real user identity
- **Tier 2**: Enterprise governance—policy controls, approval workflows, audit trails

### Allowed Domains
Allowed domains and key-level allowed origins restrict where embed keys can be used.

### End Users
End users are identified by the `sub` claim in the IDP token. Use `connect({ publishableKey, idToken })` for per-user identity.

### Organization Skills
Skills are SKILL.md files with YAML frontmatter, following the open [AgentSkills specification](https://agentskills.io). They teach the agent domain-specific knowledge using progressive disclosure.

## Agent Integration

```html
<script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js" defer></script>
<char-agent publishable-key="pk_live_..."></char-agent>
<script>
  const agent = document.querySelector('char-agent');
  agent.connect({
    publishableKey: 'pk_live_...',
    idToken: 'YOUR_IDP_JWT'
  });
</script>
```

## API Base URL

- **Production**: `https://app.usechar.ai/api`
- **OpenAPI Spec**: `https://app.usechar.ai/api/spec.json` (OpenAPI 3.1, auto-generated)

## Authentication

All API requests require a Bearer token:

```
Authorization: Bearer <your-jwt-token>
```

## MCP Servers

Connect Claude Code to Char:

```bash
/plugin marketplace add WebMCP-org/char-plugin
/plugin install char@webmcp
```

Installing the plugin auto-configures `chrome-devtools`, `char-docs`, `webmcp-docs`, and `char-saas`.

Chrome DevTools MCP fork source:
https://github.com/WebMCP-org/npm-packages/tree/main/packages/chrome-devtools-mcp

See [Install MCP Servers](/guides/mcp-servers) for details.

## Support

- Documentation: https://docs.usechar.ai
- GitHub: https://github.com/WebMCP-org/npm-packages
- Email: alex@mcp-b.ai