MCP server

Overview

Nimriz provides a remote MCP (Model Context Protocol) server at https://api.nimriz.com/mcp. It lets compatible tools operate your Nimriz workspace: create short links, look up links and domains, check slug availability, summarize link analytics, and inspect webhook and integration delivery health.

Start with the AI tools integrations page to compare supported clients and connection methods, or continue below for the complete setup reference.

The server uses the Streamable HTTP transport and responds with single JSON responses. It is workspace-scoped: every call is authorized by an OAuth grant, workspace API key, or partner token, and can only reach the workspace that credential belongs to.

Compatible customer-selected clients include OpenAI ChatGPT and Codex, Anthropic Claude and Claude Code, Cursor, Google Gemini CLI, AWS Kiro, Replit, MCP Inspector, and other compatible clients. You choose and pay for your own client account and plan. Nimriz does not provision or control those plans or tiers.

MCP is separate from the Google Sheets integration. MCP tools do not expose Google Sheet contents, selected spreadsheet identifiers or titles, tab or column configuration, Google OAuth credentials, provider request or response payloads, or provider errors. Nimriz does not use Google Workspace data to create, train, or improve generalized AI or machine learning models, and does not transfer that data to third-party AI or machine learning providers for those purposes.

---

Authentication

The MCP server supports three connection paths:

OAuth clients

Use OAuth for Claude, ChatGPT, Claude Code, Codex CLI, and any MCP client that presents Nimriz sign-in. Enter the server endpoint:

https://api.nimriz.com/mcp

Cloud connectors register with Nimriz automatically during setup. CLI clients can use the Nimriz-managed public Client IDs shown in Integrations›AI tools. The client opens Nimriz so you can choose a workspace and approve the requested scopes.

OAuth tokens for MCP are bound to the exact https://api.nimriz.com/mcp resource and cannot be used on REST API routes. If a tool needs a scope that was not approved, the client may prompt you to approve the additional permission.

Revoking the OAuth grant from the dashboard disconnects the client.

Workspace API keys

For clients that support custom headers:

1. Generate a workspace API key from Integrations›Developer›Backend API access in the dashboard. See API authentication for the full key lifecycle.
2. Send it on every request as a bearer token:

Authorization: Bearer YOUR_WORKSPACE_API_KEY

Clients whose connector settings only accept a URL can embed the key in the server URL with the api_key query parameter instead:

https://api.nimriz.com/mcp?api_key=YOUR_WORKSPACE_API_KEY

A connector URL that embeds your key is itself a secret. Anyone who has the URL can act on your workspace. Never share it, paste it into untrusted tools, or post screenshots of it; if it is ever exposed, revoke the key from the Backend API access panel and generate a replacement. The parameter only works on the MCP endpoint, and when a request carries both an Authorization header and the parameter, the header wins and the parameter is ignored.

The dashboard also has a dedicated setup page at Integrations›AI tools with OAuth setup guidance, per-client API-key fallback recipes, and inline key generation.

The key is scoped to exactly one workspace. Treat it like a password: never share it, commit it to a repository, or paste it into a browser-based tool. If a key leaks, revoke it from the Backend API access panel and generate a replacement.

Partner install tokens are also accepted and work within the scopes they were granted; tools reject a partner token that lacks the required scope.

---

Connect a client

Claude

In Claude, open Settings, choose Connectors, select Add custom connector, and use this server URL:

https://api.nimriz.com/mcp

Claude should register the OAuth client automatically, then open Nimriz sign-in. If Claude asks for an OAuth Client ID in advanced settings, use nimriz-claude-custom-mcp and leave the secret blank. Call whoami to confirm the connected workspace.

ChatGPT

In ChatGPT connector setup, use the Nimriz MCP server URL:

https://api.nimriz.com/mcp

Complete Nimriz sign-in and consent, then call whoami to confirm the connected workspace.

Claude Code

claude mcp add --transport http --scope user --client-id nimriz-claude-code-mcp nimriz https://api.nimriz.com/mcp

Follow the browser sign-in flow. Then verify the connection with claude mcp list, which should show the server as connected.

Codex CLI

codex mcp add nimriz --url https://api.nimriz.com/mcp --oauth-client-id nimriz-codex-mcp

Complete the browser approval flow, then start Codex and call whoami.

API-key fallback clients

Use the recipes below when a client cannot complete Nimriz sign-in or needs a static header or URL credential.

Claude connector URL

Claude custom connector screens can also connect with the key embedded, as described in Authentication:

https://api.nimriz.com/mcp?api_key=YOUR_WORKSPACE_API_KEY

Treat the whole URL as a secret.

Claude Code header

claude mcp add --transport http --scope user nimriz https://api.nimriz.com/mcp --header "Authorization: Bearer YOUR_WORKSPACE_API_KEY"

Paste the literal key value into the command. The stored client configuration does not expand environment variables, so a value like $NIMRIZ_KEY is sent as-is and fails with a 401.

Cursor

Add the server to your mcp.json:

{
	"mcpServers": {
		"nimriz": {
			"url": "https://api.nimriz.com/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_WORKSPACE_API_KEY"
			}
		}
	}
}

Gemini CLI

Add the server to ~/.gemini/settings.json. Note that Gemini CLI uses the httpUrl field (not url) for Streamable HTTP servers:

{
	"mcpServers": {
		"nimriz": {
			"httpUrl": "https://api.nimriz.com/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_WORKSPACE_API_KEY"
			}
		}
	}
}

Start gemini and run /mcp to confirm the server is connected.

Codex CLI header

[mcp_servers.nimriz]
url = "https://api.nimriz.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_WORKSPACE_API_KEY" }

Kiro

Add the server to .kiro/settings/mcp.json in your workspace, or to ~/.kiro/settings/mcp.json for all workspaces:

{
	"mcpServers": {
		"nimriz": {
			"url": "https://api.nimriz.com/mcp",
			"headers": {
				"Authorization": "Bearer YOUR_WORKSPACE_API_KEY"
			}
		}
	}
}

Confirm the server shows as connected in Kiro's MCP view.

Replit

In your Replit workspace, open the MCP server settings and add a server with the URL https://api.nimriz.com/mcp, then add a header with the key Authorization and the value Bearer YOUR_WORKSPACE_API_KEY.

MCP Inspector

npx @modelcontextprotocol/inspector

In the Inspector UI choose the Streamable HTTP transport, set the URL to https://api.nimriz.com/mcp, and add an Authorization: Bearer YOUR_WORKSPACE_API_KEY header.

Other MCP clients that support the Streamable HTTP transport with custom headers can connect the same way: point them at the endpoint and supply the Authorization header.

Whichever client you use, call the whoami tool first. It confirms the connection and identifies the authenticated workspace, token type, and granted scopes.

---

Available tools

Read tools

Write tools

Write tools create live links immediately. Each created link counts against your workspace's monthly link-creation limit, is recorded in the workspace audit log with the source mcp (displayed as MCP in the audit log view), and fires the link.created webhook event exactly like a link created in the dashboard or over the API.

---

Behavior notes

• Plan entitlements apply. Custom slugs, bulk creation, link expiration, and password protection follow the same plan gates as the dashboard and API. Analytics requests are clamped to your plan's analytics retention window; responses report the effective range and a range_clamped flag when clamping occurred.
• Analytics are summarized. Analytics tools return sampled aggregate counts with bot traffic excluded by default (include_bots opts in). They never return raw click records, IP addresses, or full user-agent strings.
• Bulk creation is idempotent per item. Each bulk item carries an idempotency_key; retrying an item with the same key and payload returns the stored result instead of creating a duplicate link. Items succeed or fail independently, so check the per-item results.
• Lookups are workspace- and domain-scoped. Tools only see resources in the authenticated workspace, and link lookups are strictly domain-bound with exact host matching.
• Secrets stay out of responses. Webhook signing secrets, destination credentials, and provider error payloads are never included in tool results.
• Google Workspace data stays outside MCP. Google Sheet contents and selection configuration are not included in destination list or health results.

---

Limitations

• Link update and delete operations are not available over MCP; manage existing links from the dashboard or the API.
• Webhook and integration destination management (create, update, delete) is not available over MCP; those tools are read-only health and configuration views.
• The server does not issue sessions or SSE streams. Requests are single HTTP POST calls with JSON responses; clients that require a server-initiated event stream are not supported.
• Browser-based MCP clients are not supported. Requests carrying a non-localhost Origin header are rejected.

---

Troubleshooting

---

Related guides

• AI tools integrations
• All integrations
• API authentication
• API reference
• Audit logs
• Webhooks
• Rate limits and errors