MCP server

Overview

Nimriz provides a remote MCP (Model Context Protocol) server at https://api.nimriz.com/mcp. It lets MCP-compatible AI tools such as the Claude app, Claude Code, Cursor, and MCP Inspector 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.

The server uses the Streamable HTTP transport and responds with single JSON responses. It is workspace-scoped: every call is authorized by your API credential and can only reach the workspace that credential belongs to.

---

Authentication

The MCP server authenticates with the same workspace API keys as the rest of the Nimriz API.

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, such as the Claude app's custom connector dialog, 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›Developer›MCP server with per-client connection steps 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 (desktop and web app)

The Claude app connects through a custom connector URL with the key embedded, as described in Authentication:

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

In the Claude app, open Settings, choose Connectors, select Add custom connector, paste the URL, and select Add. Treat the whole URL as a secret.

Claude Code

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

Then verify the connection with claude mcp list, which should show the server as connected.

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

Add the server to ~/.codex/config.toml:

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

---

Limitations

• Link update and delete operations are not available over MCP yet; 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.
• OAuth connection flows are not supported yet; authentication is API-key based as described above. The Claude app and claude.ai connect with the api_key connector URL described in Authentication. ChatGPT connectors require OAuth and cannot connect yet.

---

Troubleshooting

---

Related guides

• API authentication
• API reference
• Audit logs
• Webhooks
• Rate limits and errors