DOCSEARCHbyAlgolia
Submit Docs

Executor Documentation

repository·main·Indexed 25 days ago

https://github.com/usefulsoftwareco/executor

An open-source integration layer for AI agents that allows developers to configure integrations—such as MCP servers, OpenAPI, and GraphQL—with authentication and policies to expose them as a unified catalog to MCP-compatible agents. It includes a local AI executor with a CLI, local API server, and web UI, with deployment options for Cloudflare Workers and self-hosted Docker containers.

Tokens
51.9K
Snippets
115
Records
314
Agent score
84%

What's inside Executor

  1. Use @executor-js/test-servers for smoke and E2E testing

    main
    The @executor-js/test-servers package provides deployable, realistic protocol test servers designed for smoke and end-to-end tests. It exposes OAuth-protected OpenAPI, GraphQL, and MCP endpoints from a single origin. You can run tests against the in-process Worker export, via wrangler dev, or against a deployed Cloudflare Workers instance.

  2. Understand Executor's Authorization and Capability Model

    main

    Executor uses a typed capability namespace with three distinct layers to manage authority:

    1. Grants: Positive authority provided via toolkits (which act as grant bundles).
    2. Policy/Guardrails: Mechanisms for denial or required approval.
    3. Runtime: An object-capability model that prevents ambient access to the executor, raw secrets, or unrestricted network fetching.

    Capabilities are enforced via a scope()-narrowed executor acting as a membrane. The scope() function strictly intersects permissions and never widens them. Meta-capability kinds are typed, including author-tools, generate-UI, allocate-storage, deploy, trigger-register, and egress.

  3. Understand Executor telemetry data collection

    main

    Executor collects anonymous metadata to understand how product features are used.

    What is sent

    Every event includes a random per-install ID, the product surface (cli, desktop, or selfhost), the release channel, and the app version. Specific events include:

    EventPropertiesMeaning
    execution_completedok, plane (mcp/api), toolkit (boolean)A code execution finished, categorized by trigger type and toolkit scope.
    integration_addedplugin_keyAn integration was added (e.g., openapi, mcp, graphql).
    integration_removedplugin_keyAn integration was removed.
    artifact_createdvia (agent/ui)A generative-UI artifact was saved.
    artifact_viewedviaAn artifact was opened.
    artifact_updatedviaAn artifact was overwritten or renamed.
    artifact_deletedviaAn artifact was deleted.

    What is never sent

    To ensure privacy, the following are strictly excluded:

    • Code, tool arguments, tool results, or error messages.
    • Secrets, tokens, or credentials.
    • User-defined names: integration slugs, connection names, toolkit slugs, tool names, or artifact titles.
    • Identity: emails, usernames, hostnames, IP-derived locations, or organization names.

  4. Understand the Artifacts feature

    main

    Artifacts are model-generated, persistent generative UI components. They allow an AI agent to generate JSX that is saved and can be re-rendered later.

    Key characteristics:

    • Model-generated only: Artifacts are created when an MCP execute tool detects JSX in a result and the agent uses the render-ui tool.
    • Persistent & Personal: Artifacts are saved with a title and description and are owned by the generating user.
    • Dual Delivery: Depending on the MCP client's capabilities, an artifact is delivered either as an embedded UI resource (_meta.ui) for clients supporting MCP Apps, or as a deep link to the web application (/artifacts/:id) for other clients.

  5. Use @executor-js/cli for Executor projects

    main

    @executor-js/cli serves as the minimal command-line entrypoint for Executor projects.

    Note for Host Developers: Schema generation and migrations are now managed by FumaDB. Instead of generating Executor-specific storage adapters, hosts should:

    1. Build a FumaDB client using collectTables(plugins).
    2. Use FumaDB's adapter/migrator APIs directly.
    3. Ensure plugins persist through Executor's host-owned storage facades rather than contributing tables directly.

  6. Understand Executor Core Concepts

    main

    Executor is an open-source integration layer designed to represent and interoperate between software capabilities. It uses several core primitives:

    • Tool: The unit of capability, identified by <integration>.<scope>.<connection>.<tool>. It includes an optional input and output schema (JSON Schema).
    • Integration: A collection of tools produced by a plugin (e.g., from OpenAPI, GraphQL, MCP, or CLI). The core uses a normalized manifest rather than raw config.
    • Connection: A credential identified by (scope, integration, name). The name represents the specific account (e.g., work, prod).
    • Secret: A pointer (op://, keychain://, env://, vault://) held by a connection. Secrets are resolved by a provider at call time in a trusted space and never reach the agent or appear in tool I/O.
    • Scope: An ordered, merged set representing placement and identity (e.g., org | user).
    • Policy: Gates execution using allow, require-approval, or block statuses.
    • Plugin: The extension point used to register integrations, tools, providers, storage, and surfaces.
    • Manager / Invoker: The runtime roles where the Manager owns tools/config and the Invoker executes tools via connections and proxies.

  7. Benefits of using the Executor MCP Proxy

    main

    Using Executor as a proxy between your agents and tools provides several advantages:

    • Unified Endpoint: Point multiple agents (e.g., Claude Code, Cursor, ChatGPT, or custom SDKs) at a single Executor endpoint instead of configuring individual tools in every client.
    • Credential Security: Credentials for a connection are stored by Executor and attached to upstream calls. The agent operates in a sandbox and never accesses these credentials.
    • Centralized Policy Enforcement: Every tool call is governed by a policy (allow, require approval, or block).
    • Heterogeneous Integrations: Executor unifies different integration types—including upstream MCP servers, OpenAPI specs, and GraphQL endpoints—into a single catalog.

  8. Understand Astro project structure

    main

    Astro projects follow a specific directory structure for routing and assets:

    • src/pages/: Contains .astro or .md files. Each file is exposed as a route based on its filename.
    • src/components/: Recommended location for Astro, React, Vue, Svelte, or Preact components.
    • public/: Directory for static assets like images.
    • package.json: Project dependencies and scripts.

  9. Understand Executor core concepts

    main

    To use Executor effectively, understand these three core concepts:

    • Integration: The source being connected to, such as an MCP server, an OpenAPI specification, or a GraphQL API.
    • Connection: A specific, configured instance of an integration. A single integration can have multiple connections (e.g., different authentication settings for the same API).
    • Policy: The permission level assigned to each tool within a connection. Policies determine if a tool is always allowed, requires approval, or is blocked. Policies typically default to sensible values based on the spec (e.g., GET requests in OpenAPI are allowed by default).

  10. Use Executor to unify MCP, CLI, API, and GraphQL integrations

    main
    Executor is designed to solve the friction of fragmented tool access. Instead of choosing between MCP, CLI, or direct API calls, Executor accepts any input format and converts it into a standard tool catalog. This allows you to leverage the strengths of different integration methods (e.g., using an api tool modeled after CLIs like Vercel or GitHub) within a single unified interface.

  11. Understand the Integrations and Connections architecture

    main

    As of version 1.5.0, Executor has restructured how it handles external services. The architecture is now split into two distinct concepts:

    1. Integrations: These represent the API surface (e.g., Vercel, Google, etc.).
    2. Connections: These represent the credentials (e.g., a specific user account or a workspace-shared credential).

    One integration can host multiple connections. Each connection maintains its own unique tool catalog. This allows agents to target specific accounts by using the new segmented tool address format.

  12. Understand the concept of Connections

    main

    In Executor, a connection is a configured instance of an integration. While an integration defines the capability (e.g., a specific API or MCP server), a connection represents a specific usage of that integration, such as the same API authenticated for two different user accounts.

    Connections do not strictly require authentication; public APIs and public MCP servers can be used as connections without credentials. For security, Executor executes tool calls within a sandbox, ensuring that the agent cannot access the connection's credentials.