Extensions & Integrations

Overview

ArchAstro agents connect to outside systems in five ways:

Method	What it does	When to use it
Built-in integrations	Connect to GitHub, Slack, Gmail, and other supported services	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 ArchAstro
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

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

Integration	What it provides
GitHub (OAuth)	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 Bot	Post messages to channels, read channel history
Gmail	Read inbox, send emails
Outlook	Read inbox, send emails via Microsoft 365

Connect integrations through the CLI or developer portal:

archastro create agentinstallation --agent <agent_id> --kind integration/github_app
archastro authorize agentinstallation <installation_id>
archastro activate agentinstallation <installation_id>

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

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 ArchAstro 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:
  - kind: 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:

archastro 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 impersonation workflow.

---

MCP servers

ArchAstro supports connecting to remote MCP (Model Context Protocol) servers. This lets agents use any tool from the MCP ecosystem — Stripe, Notion, Sentry, Linear, and hundreds of others.

MCP servers are defined as configs:

kind: MCPServer
key: stripe-mcp
name: Stripe
url: https://mcp.stripe.com
auth:
  type: bearer
  token_source: integration

When an MCP server is connected with an integration credential, the agent gets access to all the tools that server exposes — without you writing any custom tool definitions.

---

Webhooks

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

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

Webhooks can be configured from the CLI or in the developer portal under Project -> 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.

---

The API

Everything in ArchAstro is API-first. The same operations available in the CLI and portal are available through the REST API:

• Create and manage agents, teams, threads, and messages
• Deploy configs and manage installations
• Send messages and trigger agent behavior programmatically

See the API Reference for the full specification.

---

Choosing the right approach

You want to...	Use
Connect to GitHub, Slack, or Gmail	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
Build a product on top of ArchAstro	REST API

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