Private Beta

Building, testing, and publishing agents are only available to a limited set of developers at this time.
The following documentation provides an early preview of the SDK, and the specifics are subject to change.

Connect to an MCP server¶

The Model Context Protocol (MCP) offers a standard way to expose resources and tools to LLMs. Many apps are adopting this standard and hosting MCP servers, making it easy for AI tools to interact with their data and features.

Superhuman Go agents can connect to MCP servers to take advantage of the tools provided. Adding an MCP server to an agent requires only a few lines of code, specifying an internal name and the server's URL.

pack.addMCPServer({
  name: "Icons8",
  endpointUrl: "https://mcp.icons8.com/mcp/",
});

Only one MCP server per-agent

An agent is limited to connecting to only a single MCP server. The platform expects each agent to connect to a single external application, and users wishing to work across multiple applications would install multiple agents.

Compatibility¶

MCP is a large, rapidly evolving standard, and not all MCP servers are compatible with Superhuman Go agents.

Hosted servers only - Local MCP servers (installed via npm, etc) are not supported.
Streamable HTTP transport only - Most MCP servers use the more modern Streamable HTTP transport, but the older and now deprecated HTTP+SSE transport is not supported.

Additionally, not all MCP features are supported by the platform.

Tools only - Although MCP servers can provide additional types of resources, agents can only use the tools.
No streaming support - Agents must wait for the complete response from the MCP server, and cannot take advantage of streamed responses.

Network access¶

As with all network traffic, MCP requests go through the Fetcher, and the domains used must be declared in advance. While MCP servers are often hosted on a subdomain, it's a best practice to declare the root domain to allow for future expansion to other endpoints.

pack.addMCPServer({
  name: "Icons8",
  endpointUrl: "https://mcp.icons8.com/mcp/",
});

pack.addNetworkDomain("icons8.com");

Authentication¶

Requests to MCP servers use the same authentication system as the rest of the platform. The authentication type must be declared in the code, and any client credentials must be uploaded on the Settings screen of the Pack Studio.

pack.addMCPServer({
  name: "Todoist",
  endpointUrl: "https://ai.todoist.net/mcp",
});

pack.setUserAuthentication({
  type: coda.AuthenticationType.OAuth2,
  authorizationUrl: "https://todoist.com/oauth/authorize",
  tokenUrl: "https://todoist.com/oauth/access_token",
  scopes: ["data:read_write"],
  scopeDelimiter: ",",
});

Many MCP servers do not document the required authentication type or how to register for credentials, instead supporting open-source standards for automatic discovery (RFC9728, RFC8414) and registration (RFC7591). Superhuman Go agents don't currently support these standards, so you may need to obtain this information manually. The MCP Inspector utility can inspect and test an MCP server and is helpful for manual discovery of authentication information.

Same authentication as the REST API is preferred

When possible, configure the agent's authentication to support both the MCP server and the app's REST API (if available). A Pack can only include a single type of authentication, and advanced agent features may require using the app's REST API to implement them.

User confirmation for actions¶

Superhuman Go agents prompt the user for confirmation before performing actions that mutate records or have side effects. An MCP tool will be considered such an action if the readOnlyHint annotation on the tool is any value other than true. See the ToolAnnotations type in the MCP specification for more information.