Skip to main content

​
Overview

Tool Sources define the external tools and APIs available for task execution in Executor. The Tool Sources API manages MCP servers, OpenAPI specifications, and GraphQL endpoints that provide tools to your workspaces.

​
Functions

​
upsertToolSource

Creates or updates a tool source. This is an internal mutation used by the system.
​
id
string
Unique tool source identifier. If not provided, a new ID will be generated with format src_{uuid}.
​
workspaceId
Id<'workspaces'>
required
Workspace this tool source belongs to
​
scopeType
'workspace' | 'organization'
Scope of the tool source (default: "workspace"). Organization-scoped sources are available to all workspaces in the organization.
​
name
string
required
Display name for the tool source. Must be unique within the scope.
​
type
'mcp' | 'openapi' | 'graphql'
required
Type of tool source
​
config
object
required
Configuration object for the tool source. Structure varies by type:MCP Configuration:
  • url (string): MCP server URL
  • auth (object, optional): Authentication configuration
OpenAPI Configuration:
  • spec (string | object): OpenAPI specification URL or inline spec
  • auth (object, optional): Authentication configuration
GraphQL Configuration:
  • endpoint (string): GraphQL endpoint URL
  • auth (object, optional): Authentication configuration
​
enabled
boolean
Whether the tool source is enabled (default: true)
​
id
string
Tool source identifier
​
scopeType
'workspace' | 'organization'
Scope of the tool source
​
organizationId
Id<'organizations'>
Organization ID (always set)
​
workspaceId
Id<'workspaces'>
Workspace ID (set for workspace-scoped sources)
​
name
string
Tool source display name
​
type
'mcp' | 'openapi' | 'graphql'
Tool source type
​
configVersion
number
Configuration schema version
​
config
object
Normalized configuration object
​
specHash
string
Hash of the specification for change detection
​
authFingerprint
string
Fingerprint of the auth configuration
​
enabled
boolean
Whether the source is enabled
​
createdAt
number
Unix timestamp of creation
​
updatedAt
number
Unix timestamp of last update
// Create an MCP tool source
const mcpSource = await upsertToolSource({
  workspaceId: workspace.id,
  scopeType: 'workspace',
  name: 'GitHub MCP',
  type: 'mcp',
  config: {
    url: 'https://mcp.github.com',
    auth: {
      type: 'bearer',
      mode: 'workspace'
    }
  },
  enabled: true
});

// Create an OpenAPI tool source
const apiSource = await upsertToolSource({
  workspaceId: workspace.id,
  name: 'Stripe API',
  type: 'openapi',
  config: {
    spec: 'https://api.stripe.com/openapi.json',
    auth: {
      type: 'bearer',
      mode: 'account',
      header: 'Authorization'
    }
  }
});

// Create organization-scoped GraphQL source
const graphqlSource = await upsertToolSource({
  workspaceId: workspace.id,
  scopeType: 'organization',
  name: 'Internal GraphQL API',
  type: 'graphql',
  config: {
    endpoint: 'https://api.company.com/graphql',
    auth: {
      type: 'apiKey',
      mode: 'organization',
      header: 'X-API-Key'
    }
  }
});

​
listToolSources

Lists all tool sources available to a workspace, including both workspace-scoped and organization-scoped sources.
​
workspaceId
Id<'workspaces'>
required
Workspace to list tool sources for
Returns an array of tool source objects, sorted alphabetically by name. Includes:
  • All workspace-scoped sources for the workspace
  • All organization-scoped sources for the workspace’s organization
const sources = await listToolSources({ workspaceId });

for (const source of sources) {
  console.log(`${source.name} (${source.type})`);
  console.log(`  Scope: ${source.scopeType}`);
  console.log(`  Enabled: ${source.enabled}`);
  
  if (source.type === 'mcp') {
    console.log(`  URL: ${source.config.url}`);
  }
}

​
deleteToolSource

Deletes a tool source and all associated credentials.
​
workspaceId
Id<'workspaces'>
required
Workspace context for authorization
​
sourceId
string
required
Tool source identifier to delete
Returns true if the source was deleted, false if not found or access denied. Notes:
  • Deleting a source also deletes all credential bindings associated with it
  • Organization-scoped sources can be deleted from any workspace in the organization
  • After deletion, the tool inventory is automatically rebuilt
const success = await deleteToolSource({
  workspaceId,
  sourceId: 'src_abc123'
});

if (success) {
  console.log('Tool source deleted successfully');
} else {
  console.log('Failed to delete tool source');
}

​
Tool Source Types

​
MCP (Model Context Protocol)

MCP servers provide structured tool interfaces for AI agents. 
{
  type: 'mcp',
  config: {
    url: 'https://mcp.example.com',
    auth: {
      type: 'bearer',
      mode: 'workspace',
      header: 'Authorization'
    }
  }
}

​
OpenAPI

OpenAPI specifications expose REST APIs as tools. 
{
  type: 'openapi',
  config: {
    spec: 'https://api.example.com/openapi.json',
    // or inline spec:
    // spec: { openapi: '3.0.0', ... },
    auth: {
      type: 'apiKey',
      mode: 'account',
      header: 'X-API-Key'
    }
  }
}

​
GraphQL

GraphQL endpoints provide queryable data sources. 
{
  type: 'graphql',
  config: {
    endpoint: 'https://api.example.com/graphql',
    auth: {
      type: 'bearer',
      mode: 'organization'
    }
  }
}

​
Authentication Configuration

Tool sources support various authentication methods:

​
Bearer Token

auth: {
  type: 'bearer',
  mode: 'workspace', // or 'account', 'organization'
  header: 'Authorization' // optional, defaults to 'Authorization'
}

​
API Key

auth: {
  type: 'apiKey',
  mode: 'account',
  header: 'X-API-Key' // required for apiKey type
}

​
Basic Authentication

auth: {
  type: 'basic',
  mode: 'workspace'
}

​
No Authentication

auth: {
  type: 'none'
}
// or omit the auth field entirely

​
Mixed Authentication

For sources that support multiple auth methods: 
auth: {
  type: 'mixed',
  mode: 'account'
}

​
Scope Types

​
Workspace Scope

Workspace-scoped sources are only available within a single workspace. 
await upsertToolSource({
  workspaceId,
  scopeType: 'workspace',
  name: 'Dev GitHub',
  type: 'mcp',
  config: { url: 'https://github-dev.example.com' }
});

​
Organization Scope

Organization-scoped sources are available to all workspaces in the organization. 
await upsertToolSource({
  workspaceId, // needed for org context
  scopeType: 'organization',
  name: 'Company API',
  type: 'openapi',
  config: { spec: 'https://internal-api.company.com/spec.json' }
});

​
Tool Inventory Rebuild

After upserting or deleting a tool source, the system automatically rebuilds the tool inventory:
  • Fetches updated tool definitions from the source
  • Updates available tool paths and signatures
  • Re-evaluates access policies
  • Notifies connected clients of changes
This process happens asynchronously via the scheduler. 
// After upsert or delete, inventory rebuilds automatically
await upsertToolSource({ /* ... */ });
// Rebuild is scheduled in background

// Tools become available shortly after
const tools = await listAvailableTools({ workspaceId });
  • ToolSourceType: "mcp" | "openapi" | "graphql"
  • ToolSourceScopeType: "organization" | "workspace"
  • SourceAuthType: "none" | "bearer" | "apiKey" | "basic" | "mixed"
  • CredentialScope: "account" | "organization" | "workspace"

Build docs developers (and LLMs) love

Get started for freeTalk to us