Extensions & Integrations

Overview

ArchAgents agents connect to outside systems in five ways:

Method	What it does	When to use it
Built-in integrations	Connect to GitHub and Slack with OAuth or app installations	You need an agent to read from or act in a known service
Custom tools	Define your own tool backed by a script, workflow, or HTTP endpoint	You need the agent to call your own APIs or business logic
MCP servers	Connect to any remote MCP-compatible tool server	You want to use tools from the MCP ecosystem
Webhooks	Receive inbound events from external systems	You need to trigger agent behavior from outside ArchAgents
Scripts	Write custom logic with HTTP calls, JWT auth, and data transformation	You need to call any API with full control over the request

These methods compose. An agent can use built-in GitHub integration for knowledge, a custom tool for your billing API, and a script-based routine that calls a third-party webhook — all at the same time.

---

Built-in integrations

ArchAgents has native support for connecting to common services. Each integration handles authentication, token refresh, and data access.

Integration	What it provides
GitHub (OAuth)	Personal-account repo access, issues, PRs — for knowledge indexing and code context
GitHub App	Org-wide repo access with a bot identity — for PR reviews, automated comments
Slack (OAuth)	User-level Slack workspace access
Slack Bot	Post messages to channels, read channel history

Two install scopes:

• Per-agent — one credential, one agent. Best when each agent needs its own scope or a separate workspace.

  archagent create agentinstallation --agent <agent_id> --kind enablement/github_app
  archagent authorize agentinstallation <installation_id>
  archagent activate agentinstallation <installation_id>
  

• Org-wide (Slack and GitHub only) — one OAuth grant by an org admin, every agent in the org inherits access. Best when multiple agents share the same Slack workspace or GitHub org. See Org-wide integrations for the setup path and the per-agent vs org-wide tradeoffs.

Once connected, the agent can use the integration through its builtin tools (e.g. integrations, knowledge_search) and script bindings.

See Installations for the full list of available kinds and the setup lifecycle.

---

Custom tools

When the agent needs to call your own APIs or run business-specific logic, create a custom tool.

Custom tools can be backed by:

Handler	How it works
Script	Runs an ArchAgents script that can make HTTP calls, transform data, and return results
Workflow	Triggers a multi-step workflow with branching, approvals, and external calls
HTTP endpoint	Calls an external URL directly with the tool arguments as the request body

Define custom tools in an AgentTemplate:

tools:
  - tool_type: custom
    name: lookup_order
    description: Look up a customer order by ID
    parameters:
      type: object
      properties:
        order_id:
          type: string
    handler_type: script
    config_ref: order-lookup-script

Or create them directly:

archagent create agenttool --agent <agent_id> \
  --kind custom \
  --name "lookup_order" \
  --description "Look up a customer order by ID"

See Tools for the full tool model and embed workflow.

---

MCP servers

ArchAgents supports connecting to remote MCP (Model Context Protocol) servers. This lets agents use any tool from the MCP ecosystem (Stripe, Linear, Sentry, Notion, or your own internal tool servers) without writing a custom tool for each one.

You add an MCP server to an agent's tools list:

tools:
  - kind: MCPServer
    name: linear-tools
    url: https://mcp.linear.app/mcp
    auth:
      token:
        secret_value!: <encrypted>

The platform connects to the server, discovers its tools, and exposes them to the agent automatically. Authentication supports static bearer tokens, full OAuth 2.0 flows (with discovery and dynamic client registration), and script-based auth for service-account patterns.

See MCP Servers for the full setup, all auth modes, and how MCP servers compose with the rest of the tool model.

---

Webhooks

Inbound webhooks let external systems trigger agent behavior. When ArchAgents receives a webhook, it can:

• trigger an automation
• start a workflow
• ingest data into knowledge

Webhooks are configured from the CLI, or in the developer portal under Dashboard -> Apps -> your app -> Webhooks. Each webhook gets a unique URL that external systems can POST to.

---

Scripts with HTTP access

For full control over external API calls, use scripts with the requests namespace:

let http = import("requests")
let jwt = import("jwt")
let dt = import("datetime")

// Sign a JWT for service account auth
let token = unwrap(jwt.sign({
  iss: env.CLIENT_EMAIL,
  scope: "https://www.googleapis.com/auth/cloud-platform",
  aud: "https://oauth2.googleapis.com/token",
  iat: dt.unix(),
  exp: dt.unix() + 3600
}, env.PRIVATE_KEY, "RS256"))

// Exchange for access token
let resp = unwrap(http.post("https://oauth2.googleapis.com/token", {
  headers: {"Content-Type": "application/x-www-form-urlencoded"},
  body: "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=" + token
}))

resp.body.access_token

Scripts can call any HTTP API — REST, GraphQL, webhooks, OAuth token exchanges. Combined with env variables for secrets, this gives you full programmatic access to any external service.

See Scripts and the Script Language Reference for the full language.

---

Choosing the right approach

You want to...	Use
Connect to GitHub or Slack	Built-in integration
Call your own product API from an agent	Custom tool
Use tools from the MCP ecosystem	MCP server
Trigger agent work from an external system	Webhook
Call any HTTP API with full control	Script with requests

Start with built-in integrations for supported services. Use custom tools or scripts when you need something specific to your business.