mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-05 06:59:23 +00:00
a237ebabba
* feat: adopt directory-based docs versioning with Edge channel Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com> * style: resolve linter issues --------- Co-authored-by: Cursor <cursoragent@cursor.com>
137 lines
6.7 KiB
Plaintext
137 lines
6.7 KiB
Plaintext
---
|
|
title: "Custom MCP Servers"
|
|
description: "Connect your own MCP servers to CrewAI AMP with public access, API key authentication, or OAuth 2.0"
|
|
icon: "plug"
|
|
mode: "wide"
|
|
---
|
|
|
|
CrewAI AMP supports connecting to any MCP server that implements the [Model Context Protocol](https://modelcontextprotocol.io/). You can bring public servers that require no authentication, servers protected by an API key or bearer token, and servers that use OAuth 2.0 for secure delegated access.
|
|
|
|
## Prerequisites
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="CrewAI AMP Account" icon="user">
|
|
You need an active [CrewAI AMP](https://app.crewai.com) account.
|
|
</Card>
|
|
<Card title="MCP Server URL" icon="link">
|
|
The URL of the MCP server you want to connect. The server must be accessible from the internet and support Streamable HTTP transport.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Adding a Custom MCP Server
|
|
|
|
<Steps>
|
|
<Step title="Open Tools & Integrations">
|
|
Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, then select the **Connections** tab.
|
|
</Step>
|
|
|
|
<Step title="Start adding a Custom MCP Server">
|
|
Click the **Add Custom MCP Server** button. A dialog will appear with the configuration form.
|
|
</Step>
|
|
|
|
<Step title="Fill in the basic information">
|
|
- **Name** (required): A descriptive name for your MCP server (e.g., "My Internal Tools Server").
|
|
- **Description**: An optional summary of what this MCP server provides.
|
|
- **Server URL** (required): The full URL to your MCP server endpoint (e.g., `https://my-server.example.com/mcp`).
|
|
</Step>
|
|
|
|
<Step title="Choose an authentication method">
|
|
Select one of the three available authentication methods based on how your MCP server is secured. See the sections below for details on each method.
|
|
</Step>
|
|
|
|
<Step title="Add custom headers (optional)">
|
|
If your MCP server requires additional headers on every request (e.g., tenant identifiers or routing headers), click **+ Add Header** and provide the header name and value. You can add multiple custom headers.
|
|
</Step>
|
|
|
|
<Step title="Create the connection">
|
|
Click **Create MCP Server** to save the connection. Your custom MCP server will now appear in the Connections list and its tools will be available for use in your crews.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Authentication Methods
|
|
|
|
### No Authentication
|
|
|
|
Choose this option when your MCP server is publicly accessible and does not require any credentials. This is common for open-source or internal servers running behind a VPN.
|
|
|
|
### Authentication Token
|
|
|
|
Use this method when your MCP server is protected by an API key or bearer token.
|
|
|
|
<Frame>
|
|
<img src="/images/enterprise/custom-mcp-auth-token.png" alt="Custom MCP Server with Authentication Token" />
|
|
</Frame>
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| **Header Name** | Yes | The name of the HTTP header that carries the token (e.g., `X-API-Key`, `Authorization`). |
|
|
| **Value** | Yes | Your API key or bearer token. |
|
|
| **Add to** | No | Where to attach the credential — **Header** (default) or **Query parameter**. |
|
|
|
|
<Tip>
|
|
If your server expects a `Bearer` token in the `Authorization` header, set the Header Name to `Authorization` and the Value to `Bearer <your-token>`.
|
|
</Tip>
|
|
|
|
### OAuth 2.0
|
|
|
|
Use this method for MCP servers that require OAuth 2.0 authorization. CrewAI will handle the full OAuth flow, including token refresh.
|
|
|
|
<Frame>
|
|
<img src="/images/enterprise/custom-mcp-oauth.png" alt="Custom MCP Server with OAuth 2.0" />
|
|
</Frame>
|
|
|
|
| Field | Required | Description |
|
|
|-------|----------|-------------|
|
|
| **Redirect URI** | — | Pre-filled and read-only. Copy this URI and register it as an authorized redirect URI in your OAuth provider. |
|
|
| **Authorization Endpoint** | Yes | The URL where users are sent to authorize access (e.g., `https://auth.example.com/oauth/authorize`). |
|
|
| **Token Endpoint** | Yes | The URL used to exchange the authorization code for an access token (e.g., `https://auth.example.com/oauth/token`). |
|
|
| **Client ID** | Yes | The OAuth client ID issued by your provider. |
|
|
| **Client Secret** | No | The OAuth client secret. Not required for public clients using PKCE. |
|
|
| **Scopes** | No | Space-separated list of scopes to request (e.g., `read write`). |
|
|
| **Token Auth Method** | No | How the client credentials are sent when exchanging tokens — **Standard (POST body)** or **Basic Auth (header)**. Defaults to Standard. |
|
|
| **PKCE Supported** | No | Enable if your OAuth provider supports Proof Key for Code Exchange. Recommended for improved security. |
|
|
|
|
<Info>
|
|
**Discover OAuth Config**: If your OAuth provider supports OpenID Connect Discovery, click the **Discover OAuth Config** link to auto-populate the authorization and token endpoints from the provider's `/.well-known/openid-configuration` URL.
|
|
</Info>
|
|
|
|
#### Setting Up OAuth 2.0 Step by Step
|
|
|
|
<Steps>
|
|
<Step title="Register the redirect URI">
|
|
Copy the **Redirect URI** shown in the form and add it as an authorized redirect URI in your OAuth provider's application settings.
|
|
</Step>
|
|
|
|
<Step title="Enter endpoints and credentials">
|
|
Fill in the **Authorization Endpoint**, **Token Endpoint**, **Client ID**, and optionally the **Client Secret** and **Scopes**.
|
|
</Step>
|
|
|
|
<Step title="Configure token exchange method">
|
|
Select the appropriate **Token Auth Method**. Most providers use the default **Standard (POST body)**. Some older providers require **Basic Auth (header)**.
|
|
</Step>
|
|
|
|
<Step title="Enable PKCE (recommended)">
|
|
Check **PKCE Supported** if your provider supports it. PKCE adds an extra layer of security to the authorization code flow and is recommended for all new integrations.
|
|
</Step>
|
|
|
|
<Step title="Create and authorize">
|
|
Click **Create MCP Server**. You will be redirected to your OAuth provider to authorize access. Once authorized, CrewAI will store the tokens and automatically refresh them as needed.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Using Your Custom MCP Server
|
|
|
|
Once connected, your custom MCP server's tools appear alongside built-in connections on the **Tools & Integrations** page. You can:
|
|
|
|
- **Assign tools to agents** in your crews just like any other CrewAI tool.
|
|
- **Manage visibility** to control which team members can use the server.
|
|
- **Edit or remove** the connection at any time from the Connections list.
|
|
|
|
<Warning>
|
|
If your MCP server becomes unreachable or the credentials expire, tool calls using that server will fail. Make sure the server URL is stable and credentials are kept up to date.
|
|
</Warning>
|
|
|
|
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
|
Contact our support team for assistance with custom MCP server configuration or troubleshooting.
|
|
</Card>
|