MCP Server

Connect Clavis to Claude as an MCP server. Choose between a remote OAuth 2.1 endpoint (no install required) or the local stdio npm package for Claude Desktop.

What is MCP?

The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants like Claude to securely connect to external tools and data sources. Instead of embedding credentials or writing custom API calls, you expose a set of tools that Claude can call on your behalf.

MCP servers can run locally on your machine (communicating over stdio) or remotely over HTTPS using the Streamable HTTP transport. Clavis supports both modes — the same four tools are available either way.

Two Ways to Connect

The remote MCP endpoint is a Streamable HTTP server hosted at:

https://clavisagent.com/mcp

It is protected by OAuth 2.1 using the authorization-code flow with PKCE. MCP clients that support OAuth 2.1 discovery handle the login flow automatically — they read the server metadata and redirect you to authorize. You do not manually paste tokens.

OAuth 2.1 discovery

The server publishes standard discovery documents that compliant clients use automatically:

GET https://clavisagent.com/.well-known/oauth-authorization-server

GET https://clavisagent.com/.well-known/oauth-protected-resource

Any MCP client that implements OAuth 2.1 discovery per the MCP specification will find and use these automatically. No manual configuration of token or authorize endpoints is needed.

Connecting a client

For clients that support remote MCP connections with OAuth 2.1 (such as Claude.ai):

1. In your MCP client settings, add a new remote server.
2. Enter the URL: https://clavisagent.com/mcp
3. Your client will redirect you to Clavis to authorize — log in with your Clavis account.
4. After authorizing, the client holds an access token and can call all four tools immediately.

Manual / programmatic access

If you are building a custom agent or script that calls the MCP endpoint directly, authenticate the same way as the REST API — obtain a JWT from POST /v1/auth/login and pass it as a Bearer token:

TOKEN=$(curl -sX POST https://clavisagent.com/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

curl -X POST https://clavisagent.com/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The local path runs the MCP server as a child process on your machine via npx. Claude Desktop launches it and communicates over stdio. Your Clavis JWT goes in the config file rather than through an OAuth flow.

Requirements

No separate install step is required — Claude Desktop fetches and runs the latest version via npx automatically.

Configuration

Add the Clavis MCP server to your Claude Desktop configuration file. The file location depends on your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following entry to the mcpServers section. If the file does not exist yet, create it with this structure:

{
  "mcpServers": {
    "clavis": {
      "command": "npx",
      "args": ["-y", "@clavisagent/mcp-server"],
      "env": {
        "CLAVIS_API_KEY": "eyJ...",  // JWT from POST /v1/auth/login
        "CLAVIS_API_URL": "https://clavisagent.com"
      }
    }
  }
}

After saving the config, restart Claude Desktop. You should see a hammer icon in the chat input bar indicating MCP tools are available.

Troubleshooting (local)

Claude Desktop does not show the Clavis tools

Fully quit and restart Claude Desktop after editing the config. Verify the JSON is valid (no trailing commas):

$ node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')) && console.log('valid JSON')" \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

Authentication errors

If Claude reports authentication failures, your JWT may have expired (default TTL is 24 hours). Fetch a fresh token and update the config:

$ curl -sX POST https://clavisagent.com/v1/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"email":"you@example.com","password":"yourpassword"}' \
  | python3 -m json.tool

npx fails or times out

Verify Node.js 18+ is installed and your network can reach the npm registry. You can also pre-cache the package:

$ npm install -g @clavisagent/mcp-server

Then update the config to "command": "clavis-mcp", "args": [] instead of using npx.

Available Tools

The same four tools are available regardless of which connection mode you use:

Example Usage

Once connected (via either mode), you can interact with your Clavis credentials using plain English:

NPM Package

The local stdio package is published on npm. Inspect the source, report issues, and track releases on the package page:

Next Steps