Notis for developers

When to use Notis

Use Notis when your agent needs to work with the user's connected services: find an email, check a calendar, update a project, or keep shared memory and notes. Discover the available tools for the job, inspect their schemas, and execute only what the user requested.

Choose the CLI for agents that can run shell commands, including app-building workflows. Choose hosted MCP for clients that connect to remote MCP servers without a shell. Hosted MCP exposes cloud-safe tools; desktop-only capabilities require the appropriate local Notis setup.

Start with the CLI

The official package is @notis_ai/cli on npm. Sign in through the browser, then run a discovery request:

npx --package @notis_ai/cli@latest -- notis login
npx --package @notis_ai/cli@latest -- notis doctor
npx --package @notis_ai/cli@latest -- notis tools search "find tools to read my calendar"

Use the tool name returned by discovery. Inspect its schema before preparing arguments; validate a proposed write before executing it:

npx --package @notis_ai/cli@latest -- notis tools describe <DISCOVERED_TOOL>
npx --package @notis_ai/cli@latest -- notis tools exec <DISCOVERED_TOOL> --dry-run --arguments '<JSON_ARGUMENTS>'
npx --package @notis_ai/cli@latest -- notis tools exec <DISCOVERED_TOOL> --arguments '<JSON_ARGUMENTS>'

The angle-bracket values are placeholders, not literal commands. A dry run validates the request; it does not guarantee provider success or grant permission to perform a write. Start with discovery and reads before authorized mutations. Use --json for structured CLI output, and --help for current command options.

Connect through MCP

Add this remote server URL in your MCP client's connection settings, then complete the Notis sign-in and consent flow:

https://mcp.notis.ai/mcp

Notis uses stateless Streamable HTTP, not a legacy SSE endpoint. A browser GET is not a connection test. The MCP client initializes the connection with POST and uses standard tool and resource discovery. Runtime tool schemas are the source of truth: use discovery and schema lookup rather than a saved list of integration operations.

See the Notis agent setup guides for client-specific instructions.

OAuth and least-privilege access

Notis uses authorization-code OAuth with S256 PKCE and revocable grants. The production issuer is https://mcp.notis.ai. MCP tokens target https://mcp.notis.ai/mcp; CLI credentials target https://api.notis.ai/cli. These audiences are not interchangeable. The CLI audience is for the first-party CLI, not a general-purpose REST API for third-party clients.

Use the resource-specific metadata below to request only the scopes your task needs. Scopes are capability-level permissions, not per-provider or per-record filters. Adding permissions requires the user's renewed consent.

• Notis OAuth authorization server: Machine-readable issuer, authorization, token, registration and revocation endpoints.
• Notis MCP resource metadata: The exact MCP resource audience and supported OAuth scopes.
• Notis CLI resource metadata: First-party CLI resource, scopes and release channel.

Errors and retries

Read the structured response, not just the HTTP status. OAuth errors use OAuth JSON fields such as error and error_description. MCP protocol errors and tool failures follow MCP/JSON-RPC semantics: a tool failure can arrive in an HTTP 200 response with isError. Notis tool errors include a code, message, recovery hints and request ID, and can report whether an error is retryable. CLI JSON errors likewise include structured codes and hints.

• Authentication or scope errors: sign in again or request the missing permission through consent. Repeated retries will not add access.
• Throttling: honor Retry-After when supplied. OAuth registration and authorization admission return it with rate-limit responses. Provider limits vary; there is no advertised universal requests-per-minute allowance.
• Uncertain writes: do not blindly repeat a mutation after a timeout. Check its outcome and use the interface's idempotency support where available.
• Persistent failures: retain the request ID for support, without sharing tokens or private payloads.

Versions and compatibility

MCP clients negotiate a protocol version during initialization. The server currently implements MCP 2025-11-25. Use the published CLI's @latest entry point and inspect schemas at runtime; do not treat a backend-generated OpenAPI inventory as a supported public REST contract.

Notis does not currently publish a fixed deprecation-notice period or universal Sunset-header policy for these interfaces. Follow the changelog for product changes.

Accounts and testing

The free plan includes CLI and MCP access. Sign-in and service connections are self-serve; no API key or sales call is required for this setup. Tool availability, provider permissions, plan entitlements and usage charges still apply. There is no separate public sandbox advertised here: authorized calls act on the connected account.

Read the website as Markdown

Request the same public content URL with Accept: text/markdown. Normal browser requests keep receiving HTML. Responses vary on Accept; unsupported page representations return 406. Personal result/share pages, APIs and static files are outside this negotiation.

curl -i -H 'Accept: text/markdown' https://www.notis.ai/developers/

Use the agent site index and sitemap to find pages. Unknown content paths return a real 404 with recovery links in their Markdown representation.