Changelog

Native Tool Mode

MCP clients are beginning to support Anthropic’s tool search protocol—defer_loading to mark tools as discoverable rather than always-loaded, and tool_reference content blocks to expand discovered tools into full definitions. We’ve added native mode to take advantage of this when clients support it.

From Meta-Execution to Native Tools

In meta mode, agents discover operations through find_api, learn interfaces through learn_api, and execute them through call_api. The execution path is uniform—every API call routes through the same meta-tool regardless of which operation it invokes.

Native mode preserves discovery and learning but changes execution. Operations become individual MCP tools that agents call directly. Instead of call_api("github_issues_create", { title, body }), agents call github_issues_create({ title, body }). The tool exists as a first-class entity in the agent’s tool list.

The find_api tool adapts to this change. In native mode, search results return as tool_reference content blocks. When the client receives these references, it automatically expands them into full tool definitions. The agent searches, the tools appear, and calling them is immediate.

Enabling Native Mode

Add ?tools=native to your MCP connection URL:

claude mcp add --transport http toolcog-github 'https://mcp.toolcog.com/github?tools=native'

Without the parameter, connections default to meta mode. Client support for tool search remains limited—Claude Code supports it today, Claude.ai support is coming—so native mode is opt-in rather than automatic.

Tool Metadata

An LLM analyzes each operation during indexing and generates the metadata that MCP tools need. It produces a human-readable title that clients display during invocation, and behavioral annotations that classify whether the operation is read-only, destructive, or idempotent. Clients use these annotations to decide when to prompt for confirmation, whether failed calls can be safely retried, and how to sandbox execution. Publishers upload a spec; the metadata appears without manual annotation.

Operation Pinning

Not every operation should require discovery. Some are used constantly—the handful of tools an agent reaches for in most sessions. Pinning marks these operations as always-loaded.

Pinned operations have defer_loading: false. They appear in the agent’s context from connection time, no search required. Unpinned operations have defer_loading: true and surface through find_api when needed.

Pin and unpin operations from the ellipsis dropdown menu on operation list items in the web UI.

Primary Bridges

Each owner can designate one bridge as primary. The primary bridge serves as the default when connecting to mcp.toolcog.com/{owner} without specifying a resource.

For example, mcp.toolcog.com/github resolves to the github organization’s primary bridge. Set a bridge as primary from the ellipsis dropdown menu on API or catalog list items.

Bridge Identity

The server now presents itself using the bridge’s identity rather than generic Toolcog branding. The bridge’s title, summary, and description appear in your MCP client, and meta tools include the bridge name in their titles. When you have multiple MCP servers connected, you can tell them apart at a glance.

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 arguments. 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.