Connect Adapters

aidimension Connect is a universal API adapter SDK that lets AI agents call any external service through a single, secure interface. One config file, one MCP server, every API.

Why Connect?#

Most agent apps hit the same problems:

🔑 Secrets in agent prompts — the LLM sees API keys
🔌 N×M integrations — write a new client for every service
📊 No observability — can't trace what the agent did
🐛 Cryptic errors — hard to debug

Connect solves all four:

🔒 Secrets stored in Connect, injected at request time
🔌 One adapter interface, many services
📊 Full request/response logging
🐛 Structured errors with context

Core concepts#

Connector#

A single external service. Defined in YAML or via the SDK:

# connectors.yaml
connectors:
  - name: github
    adapter: mcp-github
    auth:
      token: ${GITHUB_TOKEN}
    config:
      baseUrl: https://api.github.com

# connectors.yaml
connectors:
  - name: github
    adapter: mcp-github
    auth:
      token: ${GITHUB_TOKEN}
    config:
      baseUrl: https://api.github.com

Adapter#

A typed wrapper around an external API. Adapters expose tools that agents can call.

Tool#

A single function an agent can invoke. Each tool has a name, description, and JSON Schema for inputs.

Request flow#

Agent → MCP server → Connect → Adapter → External API
                  ↓
              (log, retry, transform)

Built-in adapters#

Adapter	Tools	Auth
`mcp-github`	40+ (issues, PRs, files, search)	PAT or GitHub App
`mcp-slack`	20+ (channels, messages, users)	Bot token
`mcp-notion`	15+ (pages, databases, blocks)	Integration token
`mcp-linear`	25+ (issues, projects, cycles)	API key
`mcp-postgres`	10+ (query, insert, update)	Connection string
`mcp-redis`	15+ (get, set, pub/sub)	URL + password
`mcp-stripe`	30+ (customers, charges, subs)	Secret key
`mcp-s3`	12+ (buckets, objects, presigned URLs)	Access key
`http`	Custom	Any (Basic, Bearer, OAuth2)

Authoring an adapter#

Adapters are TypeScript classes that implement the Adapter interface:

import { Adapter, Tool, z } from "@aidimension/connect";

class MyAdapter implements Adapter {
  name = "my-service";
  version = "1.0.0";

  tools: Tool[] = [
    {
      name: "create_item",
      description: "Create a new item in MyService",
      input: z.object({
        name: z.string().describe("Item name"),
        quantity: z.number().int().positive().default(1),
      }),
      output: z.object({
        id: z.string(),
        url: z.string().url(),
      }),
      handler: async (input, ctx) => {
        const res = await ctx.fetch("/items", {
          method: "POST",
          body: JSON.stringify(input),
        });
        return res.json();
      },
    },
  ];
}

export default MyAdapter;

import { Adapter, Tool, z } from "@aidimension/connect";

class MyAdapter implements Adapter {
  name = "my-service";
  version = "1.0.0";

  tools: Tool[] = [
    {
      name: "create_item",
      description: "Create a new item in MyService",
      input: z.object({
        name: z.string().describe("Item name"),
        quantity: z.number().int().positive().default(1),
      }),
      output: z.object({
        id: z.string(),
        url: z.string().url(),
      }),
      handler: async (input, ctx) => {
        const res = await ctx.fetch("/items", {
          method: "POST",
          body: JSON.stringify(input),
        });
        return res.json();
      },
    },
  ];
}

export default MyAdapter;

That's it. Connect handles:

✅ Registering tools with the MCP server
✅ Validating inputs against the Zod schema
✅ Injecting auth headers
✅ Logging the request/response
✅ Retrying on transient errors
✅ Rate limiting
✅ Returning errors in MCP format

Custom HTTP adapter#

For services without a dedicated adapter, use the built-in http adapter:

connectors:
  - name: my-api
    adapter: http
    config:
      baseUrl: https://api.example.com
      auth:
        type: bearer
        token: ${MY_API_TOKEN}
    tools:
      - name: get_user
        method: GET
        path: /users/{id}
        pathParams:
          - name: id
            type: string
            in: path
        output:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
            email: { type: string }

connectors:
  - name: my-api
    adapter: http
    config:
      baseUrl: https://api.example.com
      auth:
        type: bearer
        token: ${MY_API_TOKEN}
    tools:
      - name: get_user
        method: GET
        path: /users/{id}
        pathParams:
          - name: id
            type: string
            in: path
        output:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
            email: { type: string }

Using from an agent#

Once a connector is configured, the agent can call it through MCP:

// Claude Desktop / Cursor
const user = await mcp.connectors.my_api.get_user({ id: "123" });
console.log(user.name);

// Claude Desktop / Cursor
const user = await mcp.connectors.my_api.get_user({ id: "123" });
console.log(user.name);

The agent never sees the token. It just calls a typed tool with validated inputs.

Observability#

Every request is logged with:

{
  "timestamp": "2026-06-24T18:00:00Z",
  "connector": "github",
  "tool": "create_issue",
  "input": { "repo": "acme/ui", "title": "Bug" },
  "output": { "id": 42, "url": "..." },
  "duration_ms": 234,
  "status": "success"
}

{
  "timestamp": "2026-06-24T18:00:00Z",
  "connector": "github",
  "tool": "create_issue",
  "input": { "repo": "acme/ui", "title": "Bug" },
  "output": { "id": 42, "url": "..." },
  "duration_ms": 234,
  "status": "success"
}

Connect ships with a web UI at https://connect.aidimension.io/logs to search and replay requests.

Error handling#

Connect returns structured errors:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "GitHub API rate limit exceeded",
    "retry_after": 3600,
    "connector": "github",
    "tool": "create_issue"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "GitHub API rate limit exceeded",
    "retry_after": 3600,
    "connector": "github",
    "tool": "create_issue"
  }
}

Common codes:

AUTH_FAILED — token is invalid or expired
RATE_LIMITED — back off and retry
NOT_FOUND — resource doesn't exist
VALIDATION_ERROR — input didn't match schema
TIMEOUT — request took too long
INTERNAL_ERROR — adapter bug

Security#

Connect is designed to be safe to expose to agents:

🔒 Secrets never leave the server — agents never see tokens
🛡️ Input validation — every input is checked against the Zod schema
📝 Output filtering — strip secrets from responses (configurable)
🚦 Rate limiting — per-connector and per-agent
📋 Audit log — every request is logged for review
🔐 mTLS support — for connecting to internal services

Pricing#

Connect is 100% free and MIT-licensed. Self-host or use the hosted version.

✅ Unlimited connectors
✅ Unlimited requests
✅ Full observability
❌ No SLA (self-host if you need one)
❌ No support tier (community Discord)

Next steps#

SEO best practices — for the human-facing side
SEO + Connect overview — back to the section
MCP Server — protocol details