Changelog

Web Interface

The final piece: a web interface for managing APIs, catalogs, credentials, and teams.

API Management

Upload OpenAPI specifications in JSON or YAML with automatic validation and operation extraction. View and edit metadata. Download specs in either format. Generate AI-written README documentation. Pin favorites for quick access.

Catalog Composition

Create catalogs that compose operations from multiple APIs. Add sources via search combobox. Configure filters to select which operations to include. Manage variables that parameterize operations at runtime.

Service Authorization

Connect AI agents to external APIs through three entry points: global connect (pick from any API), bridge-scoped (locked to specific API or catalog), service-scoped (locked to specific service within catalog). All paths merge to a single callback URL.

OAuth Realms

Centralized management of OAuth client credentials and provider-specific variations. The toolcog organization provides pre-configured realms for major services—these work even when APIs are incorporated into other catalogs.

Scope Management

Intelligent scope merging during authorization. The consent page shows scope sources: Requested, Granted, Required. Users control the final permission set.

Variant Management

Variant selector in bridge header. Create new variants with optional spec upload. Per-variant visibility and permissions.

Operation Browser

Browse operations with rich filtering: method, service, server, auth scheme, tag, deprecation. Group by method, tag, or auth. Search by name or description.

Operation Detail

Full operation documentation: method badge, server URL, path with template variables highlighted. Parameters with name, type, required status. Request body and response schemas with expandable type references.

Vector Search

Semantic search scoped to specific APIs or catalogs. Results show matching operations ranked by similarity with their matched phrases.

Rollups

Bridge sidebar shows counts for operations, servers, auth schemes, tags, overrides, intents, sources, targets. Lazily computed with throttled sync.

Credential Management

Progressive disclosure: select bridge, then service, then auth scheme. Type-specific fields. Status indicators for expired, expiring soon, refreshing.

Vault Linking

Escrow alert when another session wants to share credentials. Accept merges credentials. Enables multi-device sharing without re-authorizing every service.

API Keys

Create API keys with label and expiration. Secret displayed once. API keys authenticate MCP clients that don’t support OAuth.

Grant Management

List all active grants with type filtering. Revoke individually with immediate effect.

Member Management

List members with roles. Edit roles via dialog. Remove with confirmation. Pending invites section.

Command Palette

Unified search (⌘K) across documentation, APIs, catalogs, operations. Scope prefixes narrow results. Quick actions for common tasks.

Documentation

Browsable docs with sidebar navigation, auto-generated table of contents, theme-aware syntax highlighting.

Blog

Post listings with pagination. Author profiles. Tag-based filtering. Reading time estimates.

Changelog

Timeline-style changelog with sticky date headers. Shareable permalinks. Pagination for historical entries.

Platform Features

With security infrastructure in place, we built out the platform features that make Toolcog usable for teams and complex use cases.

Organizations

Create organizations for team collaboration. Two-tier roles: Owner (full permissions, can manage members) and Member (read/write on Hub resources). Last-owner protection prevents demoting or removing the final org owner.

Unified Entities

Users and Organizations unified as “Owners” with shared URL patterns. APIs and Catalogs unified as “Bridges” with polymorphic behavior. The difference: APIs get operations from uploaded specs; Catalogs get operations from source references. This unification enables consistent tooling across resource types.

Resource Variants

Parallel distribution paths—more general than version numbers. URL encoding: /{owner}/{name} for main variant, /{owner}/{name}@{variant} for others. Use cases: dev/staging/production, beta channels, version variants, per-customer configurations.

Membership Invites

Invite members by email with 7-day expiration. Idempotent creation. The invite itself is authorization—no separate permission check needed.

Source Filters

Include operations from APIs or catalogs with glob-like pattern filters: service, operation, endpoint (METHOD /path), tag. Multiple sources union together. Within each source, filters AND together. Enables nested composition.

Override System

Apply transformations during operation materialization. Hierarchical matching: global → service-wide → operation-specific. Auth overrides inject credentials with strategy control and conflict resolution. Content overrides modify descriptions, servers, parameters. Overrides persist separately from specs and survive re-uploads.

Variables

Define named variables that clients pass at connection time. Hierarchical scoping. Map variable values to operation parameters. Same catalog serves different clients with different configurations.

SSE Streaming

Per-request Server-Sent Events when client accepts text/event-stream. Per-request (not session-global) to allow Durable Object hibernation.

Progress Notifications

Progress at four stages: loading operation spec, resolving credentials, executing API call, processing response. Token-driven: only sent when client provides progressToken.

Consent Elicitation

When an operation declares consequences, the system pauses and prompts the user. Five risk categories: destructive, financial, communication, access, configuration. High-risk operations omit the “always” option.

Authorization Elicitation

On 401/403 response, prompts user to authorize if streaming and client supports elicitation. Dynamic scope extraction from response headers. Retry capability: user authorizes and immediately retries.

Bridge Scoping

Three addressing patterns for MCP sessions: / for defaults, /:ownerHandle for owner with default bridge, /:ownerHandle/:bridgeHandle for explicit scoping.

Security Architecture

With the meta-tools working, we built the security layer that makes them safe to use. The core requirement: we cannot access your credentials, even with full database access.

Four-Tier Envelope Encryption

User credentials protected by layered encryption: (1) login cookie or bearer token encrypted with server key, (2) Key Encryption Key derived from token’s secret via HKDF, (3) Vault Data Encryption Key wrapped with KEK, (4) individual credentials encrypted with vault DEK. Without the user’s token, the chain cannot begin. Toolcog cannot decrypt credentials even with full database access.

Self-Routing Tokens

Session tokens contain their own routing information in encrypted form. The token identifies which account and session it belongs to without requiring a database lookup. Tokens are stateless—any edge node can validate and route them. Token types distinguished by prefix: tck* (API keys), tcs* (login sessions), tca* (OAuth access), tcr* (OAuth refresh), tcz_ (authorization codes).

OAuth 2.1 Authorization Server

Complete OAuth 2.1 implementation with mandatory PKCE for all flows. Supports authorization code, refresh token, and client credentials grants. Public clients require PKCE with no secret. Confidential clients require secret with basic or post auth method. Authorization endpoint handles consent, scope selection, and secure redirect validation.

Vault System

Logical data containers with unique IDs and DEKs. Multiple sessions and API keys can share the same vault by each wrapping the DEK with their own KEK. OAuth authorization codes carry wrapped vault DEK, enabling credential access from MCP clients.

X25519 Key Exchange

Organization vault recovery and session merging use X25519 elliptic curve key exchange. Each grant has an X25519 keypair: public key stored plaintext, private key wrapped with grant’s KEK. Initiator creates escrow with vault DEK wrapped using ECDH-derived key. Only the recipient can derive the same shared secret to unwrap.

Token Rotation

Sessions rotate automatically after 25% of lifetime elapsed. Successor chain: new token encrypted with HKDF-derived key from old secret. Old token continues working until natural expiration—no lockout if users don’t swap tokens immediately.

Permission Delegation

Fine-grained permissions delegate through the account hierarchy. Organizations grant permissions to members; members can delegate subsets to API keys. Callers can only grant permissions they have. Permission checks traverse the delegation chain. Revocation cascades automatically.

Rate Limiting

Per-account rate limiting with sliding window algorithm. Weighted count smooths transitions at window boundaries.

Credential Types

Five types: OAuth 2.0 (accessToken, refreshToken, tokenType, expiresAt, scope), API Key, HTTP Basic, HTTP Bearer, OpenID Connect. Credentials keyed by vault, bridge account, bridge resource, service name, and scheme name.

Automatic Token Refresh

Transparently refreshes expired OAuth tokens during credential resolution. Proactive refresh within 5-minute window before expiry.

The Meta-Tools

The meta-tools work. Eleven months of compiler infrastructure—context trees, schema processing, type generation, hygienic execution—converge into three tools that unlock every API without requiring tool registration per operation.

An unexpected benefit: presenting interfaces as TypeScript instead of JSON Schema dramatically improves LLM comprehension. Schema violations plummet to near zero. Token usage drops, leaving more context for actual work. Agents guess operation names and parameter structures correctly without even searching first—because TypeScript matches the code they were trained on in ways that JSON Schema never did.

find_api

Agents describe what they want to accomplish; the system searches across all indexed operations and returns matches ranked by semantic similarity. Top matches include full TypeScript function signatures with inline documentation—often enough for agents to call directly without further learning. Additional matches listed by name for broader discovery.

learn_api

When an operation has complex types or an agent needs to understand response structure, it requests expanded type declarations. The system tree-shakes the operation spec, generates TypeScript types through the optimization pipeline, and returns clean declarations that resolve all references. Request types by default; response types optional to minimize context usage.

call_api

Agents provide operation name and structured arguments organized by location (path, query, header, body). The system handles everything else: validate parameters against schemas, expand URI templates, encode the request body, resolve credentials from the user’s vault, apply authentication per security scheme, execute the HTTP request, decode the response, return structured results. Credentials never appear in the conversation.

Credential Bridge

Transforms between Auth’s storage format (with refresh tokens, expiration, scopes) and OpenAPI’s application format (just what’s needed for the request). OAuth credentials can satisfy either oauth2 schemes or http-bearer schemes—real-world APIs often declare bearer auth for endpoints that accept OAuth tokens.

Catalog Composition

Catalogs compose APIs into curated collections with visibility and override controls. Include operations from multiple APIs, exclude certain operations, override descriptions. Live updates: when source APIs change, changes propagate to catalogs via source/target messaging.

Type Generation and Intent Indexing

We’re building the new approach. Fixed meta-tools, unlimited operations, interfaces presented as TypeScript. This month: the type generator and the semantic search infrastructure.

TypeScript Type Generation

The schema compiler generates TypeScript declarations from JSON Schema—not mechanical transliteration, but the types a human would write. Discriminated unions from oneOf with discriminator properties. Eliminated impossible intersections from allOf combinations. Proper handling of optional properties vs nullable types. Clean inline types for simple schemas, named references for complex ones.

Type AST Optimization

The generator operates on an intermediate AST before emitting TypeScript. Three passes run until fixedpoint: Expand inlines type references so LLMs see actual structure. Reduce simplifies expressions—flattens nested unions, eliminates redundant constraints, removes never branches, deduplicates members. Normalize establishes consistent ordering for deterministic output.

Naive schema-to-type mapping produces technically correct but practically useless types. The optimization pipeline produces what a human would write: {name: string} | null instead of ({name?: string} & {name: string}) & ({} | null).

Keyword-Driven Type Generation

The keyword-centric architecture from December pays off. Adding type generation required no changes to core schema processing. Each keyword learned to generate its own TypeScript representation—type emits primitives, properties emits object members, allOf emits intersections. The generator traverses schemas exactly like validation does, but each keyword contributes types instead of errors.

Intent Phrase Generation

Operations indexed by intent—what they accomplish, not just their names. “Send an email” finds the right operation across different APIs even if they call it different things. A frontier model sees each operation’s synthesized TypeScript interface, documentation, and related operations, then generates natural language phrases capturing distinct reasons an agent might search for that operation. Semantic distillation: expensive comprehension amortized into phrases optimized for fast similarity matching.

Vector Indexing

Intent phrases embed into Cloudflare Vectorize for semantic similarity search. Query deduplication retrieves highest-scoring intent per operation. Metadata indexing on service name, operation name, intent ID, and phrase.

Batch Processing

OpenAI Batch API for cost-efficient intent generation. Two-stage pipeline: HTTP endpoint validates and enqueues, Durable Object processes in chunks. Lifecycle tracking with scheduled polling and exponential backoff.

Operation Metadata

Per-operation metadata indexed for efficient retrieval: method, path, servers, authentication schemes, tags. TypeScript signature generation per operation. Full-text search via FTS5.