Guide: Setting Up Your First MCP Server with a Content License

This guide walks you through connecting a Cashmere content license to an MCP-compatible application. By the end you will have a working MCP server connection and a clear path to tuning it for production.

Prerequisites: A Cashmere account and at least one content license issued to that account. If you don't have a license yet, contact your Cashmere account team.

---

Overview

• Cashmere operates a hosted MCP server — you do not run any server infrastructure yourself.
• The workflow is: receive a license → create an API key → create an MCP server in the Console → connect your MCP client → verify with a "Hello World" prompt.
• Important: sandbox licenses only work in sandbox accounts, and production licenses only work in production accounts. Environment mismatches are the most common cause of empty results or auth errors.

---

Common Workflows

Step 1 — Confirm Your Environment

Cashmere has two environments: Sandbox and Production.

When your license was issued, the sender should have indicated which environment it applies to. If you are unsure:

1. Log in at https://cashmere.io/accounts/login
2. Go to Settings → Account and check the environment shown there.

Do not mix environments. A sandbox license will not return results when used against a production account, and vice versa. If you receive an empty response or a 401 after setting up your key, environment mismatch is the first thing to check.

---

Step 2 — Create an API Key

1. Navigate to Settings → API Keys
2. Click Add Key
3. Configure:
   • Name: e.g. mcp-dev-key
   • Collections: select the collections covered by your license
   • Search model: leave as default for now
4. Copy the key immediately — it is shown only once.

Verify the key has access to your licensed content before proceeding:

curl "https://cashmere.io/api/v2/omnipubs" \
  -H "Authorization: Bearer YOUR_API_KEY"

You should get back a list of publications. If it is empty, check that the key is scoped to the correct collections and that your account is in the right environment.

---

Step 3 — Create an MCP Server in the Console

The recommended approach for application developers is to create a dedicated MCP server in the Console. This gives you per-server control over tools, parameters, response fields, and tool descriptions — all without code changes.

1. Log in and navigate to MCP Servers in the Console
2. Click Create MCP Server
3. Give your server a name and select the collections it should have access to
4. In the Tools section, enable the tools your application needs (at minimum: search_publications)
5. Save — the Console will display your server's MCP URL

---

Step 4 — Connect Your MCP Client

Cashmere's MCP server works with any MCP-compatible client. Choose the instructions for your client below.

Claude Desktop

Add the following to your Claude Desktop config file:

{
  "mcpServers": {
    "Cashmere": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.cashmere.io?api_key=YOUR_API_KEY"
      ]
    }
  }
}

ChatGPT

1. Go to Settings → Apps → Advanced settings
2. Toggle Developer mode ON
3. Click Create app
4. Enter your MCP server URL
5. Under Authentication, select No Auth if the API key is in the URL, or OAuth for custom app auth
6. Confirm the risk acknowledgment and click Create

Full guide: Creating a Custom App in ChatGPT

Other MCP Clients

Point your client's MCP server configuration at your server URL. Cashmere supports three authentication methods:

• API key in the URL:

  https://mcp.cashmere.io?api_key=YOUR_API_KEY
  

• Bearer token header:

  Authorization: Bearer YOUR_API_KEY
  

• OAuth (for custom app deployments):

  https://mcp.cashmere.io/<your-app-string>
  

For a sample implementation, see the Cashmere MCP client on GitHub.

---

Step 5 — "Hello World": Verify It's Working

Once connected, issue these two prompts in your MCP client:

1. List your publications:

"List all publications available to me through Cashmere."

This calls list_publications and should return the titles covered by your license.

2. Search your content:

"Search my Cashmere content for [a topic relevant to your licensed content]."

If both return results, your MCP server is live and your license is wired up correctly.

---

Fine-Tuning Your MCP Server

Once you have a working "Hello World," the next step is shaping the server for your specific application. Cashmere's MCP server supports four main tuning levers — all configurable in the Console without code changes:

1. Enable only the tools your application needs. The server advertises all available tools by default. Disable any tool that isn't relevant to your use case.

2. Hide parameters the agent shouldn't use. Parameters that aren't relevant to your application add noise to the agent's context and can produce unexpected behavior.

3. Hide response fields you don't need. Returning only the fields your application uses reduces token consumption and keeps agent context clean.

4. Customize tool descriptions. Rewriting descriptions in terms of your specific content domain produces significantly more reliable and predictable agent behavior.

For a complete reference of every configuration option, see Tuning Your Cashmere MCP Server.

---

Troubleshooting

Symptom	Likely cause	Fix
Empty search results	Key not scoped to the right collections, or environment mismatch	Check key collection scope and account environment (Step 1)
401 / auth error	Environment mismatch or invalid key	Verify sandbox vs. production; regenerate the key if needed
MCP client shows no tools	Server URL entered incorrectly	Double-check the URL and auth method for your client (Step 4)
Irrelevant results	Search model not suited to your content	Adjust the search model on the API key — use vtups2r-1155 (default hybrid) or vtups2n-1155 (norm fusion)

---

Further Reading

• Cashmere MCP Tools reference
• AI Search on Licensed Content
• Developer Quickstart
• Tuning Your Cashmere MCP Server