Aller au contenu

Bibliothèques · Référence

HttpApi Toolkit

An Effect AI toolkit generator that exposes selected HttpApi operations as typed dynamic tools backed by the generated API client.

Dernière mise à jour le 9 octobre 2026

Overview

makeHttpApiToolkit(config?) exposes HttpApiAdapter.operations as Effect AI tools and returns matching { toolkit, handlers }. Configuration is optional. CLI, toolkit, and MCP registration share one operation catalogue and generated HTTP client.

Read operations run without approval by default; writes require approval. Method annotations describe read-only, destructive, and idempotent behavior. Generated descriptions guide the model to wait for successful results and treat returned data as untrusted rather than as instructions.

Install

shell
bunx shadcn@latest add @krak-stack/httpapi-toolkit

Installation And Imports

Install @krak-stack/registry and import @krak-stack/registry/httpapi/toolkit and @krak-stack/registry/httpapi/adapter. Alternatively, install @krak-stack/httpapi-toolkit with shadcn and use the corresponding @/lib/httpapi-toolkit and @/lib/httpapi-adapter modules.

Configure The Adapter

ts
import { Effect, Layer } from "effect";
import { Toolkit } from "effect/ai";
import { FetchHttpClient } from "effect/http";
import { HttpApiAdapter } from "@krak-stack/registry/httpapi/adapter";
import { makeHttpApiToolkit } from "@krak-stack/registry/httpapi/toolkit";
import { AppApi } from "@/api";

const adapterLayer = HttpApiAdapter.layer({
  api: AppApi,
  baseUrl: "https://example.com",
  methods: ["get"],
}).pipe(Layer.provide(FetchHttpClient.layer));

Explicitly select GET operations for read-only exposure. Omit methods or select additional methods only when intentionally exposing writes. Use include to narrow selection further.

Compose With An Agent

Inside the application's Effect program:

ts
const { toolkit: httpTools, handlers } = yield* makeHttpApiToolkit().pipe(
  Effect.provide(adapterLayer),
);
const definition = Toolkit.merge(application.toolkit, httpTools);
const toolsLayer = Layer.mergeAll(
  application.layer,
  handlers.pipe(Layer.provide(adapterLayer)),
);
const toolkit = yield* definition.pipe(Effect.provide(toolsLayer));

const events = yield* agent.stream({
  action: request.action,
  history: request.history,
  systemPrompt: application.systemPrompt,
  toolkit,
});

application, agent, and request belong to the consuming application. Tool arguments use { params, query, headers, body }, with typed numeric and boolean parameters rather than wire strings. Payload codecs preserve their transformations. Override needsApproval to customize the agent's approval policy. Use strict for OpenAI-compatible strict object schemas and transformResult to reduce or redact responses. Construct once; the separate HttpApiToolkit and HttpApiToolkitLayer factories have been removed.

Serve A Toolkit Over MCP

Register the toolkit directly with Effect; no HTTP API-specific MCP service is needed. Keep server identity and transport in the consuming application:

ts
import { McpProtocol, McpServer } from "effect/ai";

export const mcpLayer = Layer.effectDiscard(
  Effect.gen(function* () {
    const { toolkit, handlers } = yield* makeHttpApiToolkit();
    yield* McpServer.registerToolkit(toolkit).pipe(Effect.provide(handlers));
  }),
).pipe(
  Layer.provideMerge(
    McpServer.layerHttp({
      name: "app",
      version: "1.0.0",
      path: "/api/mcp",
      protocols: [McpProtocol.v2025_11_25],
    }),
  ),
  Layer.provide(adapterLayer),
);

This example reuses the imports and GET-only adapterLayer above. Provide mcpLayer alongside the application's routes in its HTTP runtime. Any Effect toolkit, including non-HTTP tools, can be registered this way.

Inbound MCP authentication and authorization remain application-owned. Provide an authenticated HttpClient when the downstream API requires credentials; never expose credentials as tool arguments. Method annotations are not access controls. If intentionally exposing writes, enforce authorization or confirmation in the application before opting out of agent approval with needsApproval: () => false. Registration does not silently disable approval requirements.

The HttpApiMcp service and registry item have been removed. ApiClient and HttpApiSpec have also been replaced by the single HttpApiAdapter dependency.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies

Registry Dependencies