Connect an assistant to the Spisko MCP server

Connect Claude

Connecting an assistant comes with Spisko Plus. If Plus ends, your connections and tokens stay, and they work again once Plus is back.

1. In claude.ai or Claude Desktop, open Settings › Connectors and choose Add custom connector.
2. Name it Spisko and paste the server URL: https://spisko.com/api/mcp. There is nothing else to fill in.
3. Claude opens Spisko. Sign in, read what the assistant asks to do (view, or view and edit, your inventory and shopping lists) and choose Allow.

That’s it: ask Claude to “add eggs and coffee to my weekly list”. A connection lasts 90 days, then Claude asks you to connect again. What else to ask.

Other MCP clients: a personal access token

A client that doesn’t sign in by itself takes a personal access token in a header instead. The server speaks MCP over Streamable HTTP.

1. In Spisko, open Settings › API and choose Generate Token.
2. Name it after the client, choose how long it lasts (30 days to a year) and whether it may change things (Read & write) or only look (Read only).
3. Copy the token. It starts with slp_ and is shown only once.
4. Give your client the server URL and the token as Authorization: Bearer <token>.

{
  "mcpServers": {
    "spisko": {
      "type": "http",
      "url": "https://spisko.com/api/mcp",
      "headers": { "Authorization": "Bearer slp_your_token" }
    }
  }
}

{
  "mcpServers": {
    "spisko": {
      "command": "npx",
      "args": ["mcp-remote", "https://spisko.com/api/mcp", "--header", "Authorization: Bearer ${SPISKO_TOKEN}"],
      "env": { "SPISKO_TOKEN": "slp_your_token" }
    }
  }
}

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

Keep a token secret: it opens your account to whoever has it. Make one per client, so you can revoke one without the others.

What an assistant can do

The server offers twelve tools. An assistant picks them itself from what you ask; the examples show the kind of request each one answers. On a read-only connection only the four that look work (list_inventory, suggest_restock, list_shopping_lists and list_themes); the others answer that the connection is read-only.

• list_inventory

  Your inventory items with their quantities and aisle, optionally only what’s running low or one category.

  Input low_stock_only?, category?

  What’s running low at home?

• add_item

  Adds an item to your inventory.

  Input name, description?, current_quantity?, goal_quantity?, unit?

  Add olive oil to my pantry. I like to keep two bottles.

• set_quantity

  Changes how much of an item you have, by an amount or to a value, and how much you like to keep.

  Input item_id, delta?, current_quantity?, goal_quantity?

  I used the last two eggs.

• suggest_restock

  Items running low: down to half of what you like to keep, or less.

  Input {}

  What should I buy this week?

• list_shopping_lists

  Your shopping lists.

  Input {}

  What lists do I have?

• create_shopping_list

  Makes a new list.

  Input name, description?, status?

  Make a list called Party.

• add_to_list

  Puts something on a list: an inventory item, or just a name. The answer says which aisle it’s in.

  Input shopping_list_id, item_id? or name?, quantity?, unit?

  Add the ingredients for this recipe to my Groceries list.

• check_off

  Ticks something on a list off, or back on.

  Input shopping_list_item_id, checked?

  Tick off the milk, I’ve got it.

• list_themes

  The themes you’ve made.

  Input {}

  Which themes have I made?

• create_theme

  Makes a theme from seven colours, with corner radius, shadows and, with Plus, a background, a font and CSS.

  Input name, colors, radius?, shadows_enabled?, background_image_url?, font_family?, custom_css?

  Make me a dark theme with green accents.

• update_theme

  Changes a theme you’ve made.

  Input theme_id, then any field create_theme takes

  Make the corners on my theme rounder.

• delete_theme

  Deletes a theme you’ve made.

  Input theme_id

  Delete the Midnight theme.

What an assistant can see

• Only what your own account owns: your items, your lists and your themes. Lists someone else shares with you stay out of reach.
• Each request acts as your account, so the same rules apply as in the app.
• Settings › API lists your tokens with when each was last used, and Connected Apps lists the assistants you’ve allowed. Revoke token and Revoke access cut one off at once.

Troubleshooting

• 401 Unauthorized: the token is wrong, revoked or expired. Generate a new one, or connect the assistant again.
• 403, “comes with Spisko Plus”: the account has no Plus. Your tokens work again as soon as it does.
• “This connection is read-only”: the token or connection only looks. Make a Read & write one.
• No tools show up: check that the URL ends in /api/mcp, then restart the client. In a config file, check the JSON is valid.