Personal and workspace ownership
Configured tool accounts and MCP servers can belong either to a workspace or to you personally. Personal resources are organization-bound for billing and administration, but they are not attached to a team. Only you and organization or system administrators can manage them. A workspace MCP server can optionally federate personal tools for each connecting user:- None exposes only the server’s workspace tools.
- All personal tools adds every active personal tool owned by the caller.
- Selected personal tools adds only allowed provider and tool definitions that the caller has configured.
Share without giving up control
Tool groups, proxied MCP servers, custom tool providers, MCP server instances, and managed credential roots use independent visibility and ownership planes. For tool and MCP roots, visibility controls safe discovery and use. Ownership controls configuration, tool selection, federation policy, grant management, and deletion. Set either plane to Team or Private, then add private grants for an Identity user or group. Ownership and administrator access do not make a private resource visible. Credential visibility exposes only redacted metadata needed for discovery. It never authorizes secret retrieval or returns plaintext or decrypted values. Secret configuration, brokering, rotation, and deletion require ownership, while a bound consuming resource receives only the exact capability it needs at execution time. Global MCP and runtime MCP responses do not reveal stored provider secrets. Definitions, configured tools, and runtime mappings inherit their owning tool or MCP root. A shared MCP server resolves caller-specific personal federation after authentication, so one user’s accounts and credentials cannot appear in another user’s catalog. When Tilde provisions several surfaces for one common provider, the common-provider installation is their policy root. Its live visibility and ownership policy applies to the generated tool group, ChatKit provider, signal provider, and reverse-proxy profiles. Manage the policy at/api/v1/team/{team_id}/credential/common-provider-installation/{id}; a bound
child cannot widen it independently. Credential secret administration remains
separate from provider-bundle visibility.
MCP authorization is intersected at execution time: visibility of an MCP
server does not by itself authorize a private tool group, and visibility of a
tool group does not authorize connection through a private server.
Enable off-the-shelf tool providers, add custom tools, or proxy upstream APIs. Group them in an MCP server, then connect your agent with the Tilde SDK.
1
Enable tools from a source
Open Tilde, select your workspace, and go to Tools. Choose one of these sources:
- Configure Tools for managed providers such as GitHub, Gmail, and Slack.
- Proxied MCP servers to connect an existing Streamable HTTP MCP server.
- Custom Tools to register your own remote tool endpoints.
2
Create an MCP server and add tools
- Go to Tools → MCP Servers and click Add MCP server.
- Name the server. Enable dynamic mode if the agent should search a large tool catalog instead of loading every tool definition into context.
- Open the server and add tools from your configured providers, proxied MCP servers, or custom tool providers.
- Adjust tool names, descriptions, parameters, or fixed inputs as needed.
- If callers should bring their own personal tools, choose All personal tools or Selected personal tools. The default is None.
3
Connect with the Tilde SDK
Install the Tilde SDK and MCP client packages.Add the MCP server ID and your Tilde credentials to the app’s environment. Find the organization and team IDs under Settings → Team settings → General information.Create the Tilde client, then use
.env.local
process.env.TILDE_MCP_SERVER_ID when creating the MCP client.lib/tilde-tools.ts
createMCPClient constructs the Tilde MCP endpoint and authenticates it with your Tilde API key. Keep the client open while the agent uses its tools, then call closeMcp().Inside a ChatKit endpoint using responseMode: "tool", call context.session.createMCPClient({ serverId: process.env.TILDE_MCP_SERVER_ID! }) instead. The returned MCP client includes the current provider’s session-bound communication tools, with channel, thread, participant, and recipient routing supplied by ChatKit rather than the model.Use context.mcp.connect({ serverId }) when a shared ChatKit agent should apply the MCP server’s personal-tool federation policy to the verified speaker. This connection forwards a private, invocation-scoped capability. Do not place that capability or a user/account identifier in tool arguments, messages, logs, or configuration.Add another Tilde agent as a tool
Registering a ChatKit agent automatically creates a credentialless Message agent tool provider bound to it. Open the MCP server that your parent agent uses and add both generated tools:messagesends Vercel AI SDK-compatible message parts and immediately returns a ticket plus a ChatKit session ID.wait_for_responsesubscribes to ChatKit in real time, emits the child response as MCP progress or logging notifications, and returns the persisted canonical ChatKit message when the turn finishes.
message to continue a child conversation. The target agent’s queue, interrupt, or queue-and-batch policy applies automatically.
Connect a hosted MCP provider
Open Tools → Proxied MCP servers → Browse provider catalog to connect a hosted MCP provider. The catalog includes ready-to-configure providers such as Notion, Granola, Browserbase, Parallel, Intercom, Zoom, Salesforce, Clay, Apollo, and HubSpot, alongside public documentation MCP servers. Tilde loads a reviewed tool-definition snapshot before you connect credentials, so the provider’s tools can be inspected and selected in the same way as managed provider tools. After authentication, Tilde calls the upstream server’stools/list method and reconciles the deployed definitions with the live catalog. Providers are published in the connectable catalog only after a validated snapshot exists.
The catalog records whether a snapshot came from an unauthenticated tools/list response, an official source repository, or official provider documentation. Definitions inferred from source or documentation are replaced by the authenticated upstream response as soon as the provider permits discovery.
Authentication follows the upstream server:
- OAuth providers use PKCE and published authorization metadata. Providers that support dynamic client registration create a new client for the current Tilde environment.
- Manual OAuth providers ask for the provider’s registered client ID and client secret.
- API-key and bearer-token providers ask for the secret and the header or query-string placement required by the server.
- Public documentation servers connect without credentials.
Dynamic mode
Dynamic mode exposesSEARCH_TOOLS, GET_TOOL_SCHEMAS, and MULTI_EXECUTE_TOOL instead of loading every tool schema into the model’s context at once. The agent searches for relevant tools, loads only the schemas it needs, and can execute several tools together.
We recommend enabling dynamic mode by default. It is especially useful when an MCP server contains many tools or its toolset changes frequently. Use static mode only for a small, fixed toolset where you want every tool to be immediately visible to the model.
Remote custom tools
Use a remote custom tool when the implementation should run independently from the agent and be reusable across multiple agents. Your server exposes a discovery manifest and an invocation endpoint. Tilde signs both requests with the custom tool provider’s signing key.toolEndpoint exposes the discovery and invocation handlers, validates both Zod schemas, and verifies that every request came from Tilde.
app/api/tools/route.ts
GET /api/tools URL as the discovery URL. Save the one-time signing key as TILDE_CUSTOM_TOOL_SIGNING_KEY, redeploy, then refresh the provider so Tilde can discover the manifest.
By default, toolEndpoint derives the public invocation URL from the incoming request. If a proxy rewrites the public origin or path, set baseUrl, endpointPath, or both.
Local custom tools
Use a local custom tool when it needs in-process state, request context, or code that should not be deployed separately. Pass Vercel AI SDK tools tocreateMCPClient; they are returned alongside the tools from your Tilde MCP server.
wherever-you-create-your-agent.ts
Reverse proxy
Use a reverse proxy when your application or a third-party SDK needs the provider’s native API instead of an MCP tool. Tilde injects the credential attached to the reverse-proxy profile, so the upstream credential does not need to enter your agent’s environment. Reverse-proxy profiles have independent visibility and ownership. Visibility controls discovery and proxy invocation. Ownership controls the upstream URL, credential bindings, injected headers, enabled state, grants, and deletion. Seeing or invoking a profile never grants access to the credential’s metadata, secret, or settings; the proxy receives only an exact internal consumption capability after profile authorization. The code review bot uses this pattern to clone repositories through a GitHub Git HTTPS profile and connect to Modal through a gRPC profile.github-api.ts
Personal OAuth through provider setup
Applications can reuse the workspace provider catalog while creating an account owned by the signed-in user. Sendpersonal: true to
POST /api/v1/team/{team_id}/provider-setup/start, together with the catalog’s
provider and authentication method IDs. Use a distinct form_values.id for each
account and supply return_url for the OAuth callback.
Personal OAuth stores both the connection and its refreshable credential in the
user scope. Tokens use the user’s encryption key. Tilde ensures the owner’s
scoped key exists before OAuth starts and again when resuming a callback,
including for accounts created before personal encryption was introduced. The callback preserves custom
account labels alongside the provider’s account identity. Read the resulting
accounts from /api/v1/user/{user_id}/mcp/tool-group. Workspace-owned setup remains
the default when personal is omitted. Agents use these accounts through
session-bound personal tool federation rather than receiving credentials.