DOCSEARCHbyAlgolia
Submit Docs

Archestra Documentation

repository·main·Indexed 26 days ago

https://github.com/archestra-ai/archestra

An open-source enterprise AI platform providing a secure, observable gateway for LLMs, MCP (Model Context Protocol) tools, and autonomous agents. The repository includes the ai-labs Rust workspace and archestra-bench, an agentic benchmark and trajectory generator used to prototype AI features, analyze trajectories via the trajectory-analyzer tool, and verify task results using pytest verifiers.

Tokens
176.3K
Snippets
197
Records
880
Agent score
85%

What's inside Archestra

  2. Overview of MCP Orchestrator

    main

    The MCP Orchestrator is used to run self-hosted Model Context Protocol (MCP) servers within a Kubernetes cluster. It automates the creation of Kubernetes deployments, injects necessary configuration and secrets, exposes logs and status within the Archestra platform, and connects these servers to Agents and MCP Gateways.

    Note: The orchestrator is only required for MCP servers that Archestra hosts. Remote MCP servers can be managed via the Private MCP Registry and exposed through MCP Gateways without creating Kubernetes deployments.

  3. Overview of LLM provider implementation requirements

    main

    Adding a new LLM provider to the Archestra Platform requires implementing two primary components:

    1. LLM Proxy: A proxy layer that sits between clients and LLM providers. It is responsible for:
      • Security policies
      • Tool invocation controls
      • Metrics and observability
      • Handling both streaming and non-streaming provider responses
    2. Chat: Integration with the built-in chat interface.

  4. Overview of ai-labs and archestra-bench

    main

    The ai-labs Rust workspace is used for prototyping Archestra's AI features. Its primary component is archestra-bench, an agentic benchmark and trajectory generator.

    It works by grouping tasks into environments (defined in envs/<id>.toml). Each environment:

    1. Boots an isolated Archestra backend on a fresh port with a dedicated Postgres database.
    2. Seeds the environment with web-pinned skills, remote MCP servers, and a specific agent.
    3. Drives agentic chat sessions to solve tasks.
    4. Grades answers out-of-band using a verifier.
    5. Tears down the instance and aggregates results by environment and task.

  5. Overview of Archestra Identity Provider Capabilities

    main

    Archestra supports Identity Providers (IdP) for two primary functions:

    1. Sign-in (SSO): Users authenticate using existing IdP credentials.
    2. Downstream MCP tool calls (Enterprise-Managed Auth): Archestra exchanges the user's IdP token for a downstream API token at tool-call time, allowing tools to run as the specific user rather than a service account.

    Supported Protocols and Features:

    ProviderProtocolSSORole mappingTeam syncToken exchange
    Microsoft Entra IDOIDCYesYesYesEntra OBO
    OktaOIDCYesYesYesOkta-managed
    GoogleOIDCYesYesYesRFC 8693
    GitHubOIDCYesYesYesRFC 8693
    GitLabOIDCYesYesYesRFC 8693
    Generic OIDCOIDCYesYesYesRFC 8693
    Generic SAMLSAML 2.0YesYesYesN/A

    Note: Token-exchange strategy is auto-inferred from the OIDC issuer URL (Okta hostnames → Okta-managed, Microsoft hostnames → Entra OBO, others → RFC 8693).

  6. Overview of Archestra MCP Server

    main

    The Archestra MCP Server is a built-in Model Context Protocol (MCP) server included with the platform. It requires no installation and provides tools for managing platform resources, including agents, MCP servers, policies, and limits.

    Key characteristics:

    • Prefixing: All Archestra tools are prefixed with archestra__.
    • Default Tools: New agents are pre-installed with todo_write and query_knowledge_sources by default.
    • Tool Availability: query_knowledge_sources is only available for Agents and MCP Gateways when at least one knowledge base or connector is attached. Using it requires the knowledgeSource:query permission.
    • Trust Model: Most built-in tools are 'trusted' and bypass tool invocation and trusted data policies. However, query_knowledge_sources is an exception; its output is treated as sensitive by default and is subject to trusted data policies.

  7. Overview of Archestra Platform Components

    main

    Archestra is a centralized AI platform designed for both non-technical users and engineers. It provides a unified environment where non-technical users interact via chat interfaces, while engineers build agents using existing stacks (LangChain, n8n, Python, etc.) leveraging Archestra's MCP orchestrator, guardrails, and observability tools.

    Key components include:

    • Agentic Chat: A web UI, Slack, MS Teams, or Email interface for interacting with agents.
    • Agent Runtime: A no-code builder for defining system prompts, assigning MCP tools/sub-agents, and configuring triggers.
    • MCP Orchestrator: Runs MCP servers as isolated pods within Kubernetes.
    • Knowledge Base: A built-in RAG (Retrieval-Augmented Generation) system for agent data access.
    • LLM & MCP Proxies: A drop-in proxy for LLM providers and an MCP Gateway that provides a single endpoint for all MCP tools. Compatible with n8n, LangChain, Vercel AI, Pydantic AI, and Mastra.
    • Security & Guardrails: Provides deterministic tool invocation and trusted data policies to prevent prompt injection bypass.
    • Observability: Includes Prometheus metrics, OpenTelemetry tracing, and per-team cost tracking.

  8. Understand the Knowledge Base Architecture

    main

    The Archestra RAG (Retrieval-Augmented Generation) stack is built entirely within PostgreSQL using pgvector, eliminating the need for an external vector database.

    Ingestion Process

    Connectors operate on a cron schedule. The workflow is:

    1. Connectors fetch data.
    2. Documents are generated.
    3. Chunking splits documents into manageable pieces.
    4. Embedding is performed via an Embedding provider API.
    5. Data is stored in PostgreSQL + pgvector.

    Querying Process

    When an agent performs a query, the following workflow occurs:

    1. Agent Query is sent to the Embedding provider API to create a Query Embedding.
    2. Vector Search and Full-Text Search (FTS) (if configured) run in parallel using the query embedding.
    3. Results from both searches are combined using Reciprocal Rank Fusion (RRF).
    4. Results undergo Reranking.
    5. ACL Filtering (Access Control List) is applied to ensure data privacy.
    6. Final Results are returned to the agent.

  9. Understand MCP Authentication Layers

    main

    Archestra implements a two-layer authentication model for Model Context Protocol (MCP) interactions. This separation allows clients to authenticate once to a gateway while Archestra manages diverse credential models for various upstream tools.

    1. Gateway authentication: The method used by an MCP client (e.g., Cursor, Claude Desktop, Copilot CLI) to prove it is authorized to call the Archestra gateway endpoint: POST /v1/mcp/<gateway-id>.
    2. Upstream MCP server authentication: The method Archestra uses to authenticate to the specific MCP server or external system (e.g., GitHub, Jira) when a tool is executed.

    Clients only need to provide the gateway-facing token. Archestra resolves the necessary upstream credentials at execution time based on the caller identity, gateway/Agent tool assignment, and the configured MCP server credentials.

  10. Understand Archestra Platform licensing and pricing

    main

    Archestra follows an Open Core model. The base platform is licensed under AGPL-3.0. Certain advanced features are subject to the Archestra Enterprise License.

    Small Team Exception

    If your total company-wide user count for Archestra.AI is fewer than 30, you may use Enterprise features in production without a paid subscription or Enterprise license. Once your user count reaches 30 or more, you must obtain a valid Enterprise license to continue using these features in production.

  11. Understand the two-step authorization model

    main

    Archestra uses a two-step authorization process for scoped resources:

    1. RBAC (Role-Based Access Control): Grants base actions such as read, create, update, or delete.
    2. Runtime Scope Rules: Further restricts which specific records a user can see or modify based on the resource's scope.

    Common scopes include:

    • personal: Owned by a single user.
    • team: Shared with one or more teams.
    • org: Shared across the entire organization.

  12. Choose an MCP Gateway authentication method

    main

    The MCP Gateway supports six authentication methods depending on the caller type and whether per-user identity (required for Resolve at call time) is needed:

    MethodBest ForActing UserNotes
    OAuth 2.1Interactive clients (Claude Desktop, Cursor, etc.)YesAutomatic discovery; supports DCR/CIMD.
    OAuth client credentialsMachine-to-machine (backend services, bots)NoPre-registered client scoped to specific gateways.
    OAuth authorization codeAgentic chat backends acting for usersYesConfidential client; enables per-user resolution.
    Bearer tokenDirect API integrations and scriptsPersonal onlyUses static platform tokens (arch_<token>).
    ID-JAGCorporate IdP-managed clientsYesRFC 8693 token exchange; validates IdP-issued JWT.
    JWKSClients presenting external IdP JWTs directlyYesValidated against profile IdP; no Archestra token issued.