OwlectOwlect
Get Started Free

Developers · MCP

Use Owlect from Claude and ChatGPT

Owlect runs a remote Model Context Protocol (MCP) server. Add it to your AI assistant once, sign in with Google, and manage your collections by chatting: add a whole shelf from a list or a photo, fix details, mark things for sale, or ask questions about what you own.

Server URL

https://owlect.app/api/mcp
Remote MCPStreamable HTTPOAuth 2.1 + PKCE11 toolsView as Markdown →

What you can ask

Once connected, talk to your assistant normally. It picks the right Owlect tools on its own.

  • “Add these 20 board games to my shelf: [paste a list or attach a photo]”
  • “Mark everything by Stonemaier in my board games as for sale at $40”
  • “Which of my LEGO sets are incomplete?”
  • “Create a vinyl collection called ‘Jazz’ and add the albums in this photo”
  • “How many items do I have left on my plan?”
  • “Rename my ‘Wishlist’ collection to ‘To buy’”

Quick start

  1. 1

    Copy the server URL

    The URL above works in every client. You do not need an API key.

  2. 2

    Add it to your assistant

    In Claude or ChatGPT, add a custom connector (called an app in ChatGPT) with that URL. Step-by-step guides for each client are below.

  3. 3

    Sign in and allow access

    Your assistant opens Owlect. Sign in with the Google account you use for Owlect, check which app is asking, choose what it may do, and click Allow.

Set up your client

Owlect works with any client that supports remote MCP servers with OAuth sign-in. Guides for the most common ones follow.

Claude (web, desktop and mobile)

Custom connectors are available on all Claude plans. The Free plan allows one custom connector.

  1. 1Open claude.ai and go to Settings -> Connectors.
  2. 2Click "Add custom connector".
  3. 3Name it "Owlect" and paste the server URL. Leave the OAuth client fields empty: Owlect registers Claude automatically.
  4. 4Click Add, then Connect. Sign in to Owlect with Google and click Allow.
  5. 5In a chat, open the + menu -> Connectors and make sure Owlect is switched on.

Connectors you add on claude.ai also appear in the Claude desktop and mobile apps. On Team and Enterprise plans, an owner has to add the connector for the organization first.

ChatGPT

ChatGPT connects to custom MCP servers in developer mode.

  1. 1Open ChatGPT on the web and go to Settings -> Apps & Connectors -> Advanced settings, and switch on Developer mode.
  2. 2Back in Apps & Connectors, click Create.
  3. 3Name it "Owlect", paste the server URL and choose OAuth for authentication.
  4. 4Click Create. A sign-in window opens: sign in to Owlect with Google and click Allow.
  5. 5In a new chat, pick Owlect from the tools menu (+) so ChatGPT can use it.

Developer mode and custom apps depend on your ChatGPT plan and workspace settings. If you do not see the option, your workspace admin may need to allow it.

Claude Code

Add the server from your terminal, then sign in from inside Claude Code.

  1. 1Run the command below.
  2. 2Start Claude Code, type /mcp, choose owlect and pick Authenticate. Your browser opens the Owlect sign-in.
bash
claude mcp add --transport http owlect https://owlect.app/api/mcp

VS Code (GitHub Copilot agent mode)

Add Owlect to your workspace or user MCP configuration.

  1. 1Create .vscode/mcp.json (or open the user MCP config) with the snippet below.
  2. 2Click Start above the server entry. VS Code opens the Owlect sign-in in your browser.
json
{
  "servers": {
    "owlect": {
      "type": "http",
      "url": "https://owlect.app/api/mcp"
    }
  }
}

Cursor and other clients

Clients that only speak stdio, or that sign in through a custom URL scheme (such as cursor://), can connect through the mcp-remote bridge, which runs the sign-in on localhost.

  1. 1Add the snippet below to the client's MCP configuration (for Cursor: ~/.cursor/mcp.json).
  2. 2Restart the client. mcp-remote opens the Owlect sign-in in your browser the first time.
json
{
  "mcpServers": {
    "owlect": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://owlect.app/api/mcp"
      ]
    }
  }
}

Owlect only accepts https redirect addresses, or http on localhost. That is why custom URL schemes need the bridge.

MCP Inspector (for developers)

The official Inspector is the quickest way to see the tools and try calls by hand.

  1. 1Run the command below.
  2. 2Choose Streamable HTTP, paste the server URL and click Connect. Complete the sign-in, then open the Tools tab.
bash
npx -y @modelcontextprotocol/inspector

Tools

Every tool acts only on the signed-in user's own data. The assistant never passes a user id: it comes from the access token.

Read

Safe to call anytime. Need the read permission, which every connection has.

get_account

Read

Your plan, and how many items and collections you have used out of your limits.

No parameters.

list_collections

Read

All your collections with their type, item count and public link, most recently updated first.

No parameters.

get_collection

Read

One collection with its custom fields (key, label, type, allowed options). Assistants call this before adding or editing items so values land in the right fields.

  • collectionIdRequired

    uuid

    Id of one of the user's collections (from the collection list).

search_items

Read

Items in one collection, newest first, with an optional name search and for-sale filter. Returns pages with a cursor for the next page.

  • collectionIdRequired

    uuid

    Collection to search.

  • query

    string, max 200

    Case-insensitive match on the item name.

  • forSale

    boolean

    true for items listed for sale, false for the rest.

  • limit

    integer 1-50, default 20

    Items per page.

  • cursor

    string (nextCursor from the previous page)

    nextCursor from the previous page. Omit it for the first page.

get_item

Read

One item with every field, including custom field values, sale details and cover image.

  • itemIdRequired

    uuid

    Id of an item (from listing or searching a collection).

Write

Create tools need the create permission, update tools the update permission.

create_collection

Write

Creates a collection. Built-in types come with their standard fields. The custom type needs Owlect Plus.

  • nameRequired

    string, 1-100

    Collection name.

  • typeRequired

    dolls | board_games | coins | stamps | music | pokemon_cards | sneakers | retro_games | funko_pop | lego | comic_books | books | watches | cars | hot_wheels | custom

    Collection type. Decides the default fields and the lookups used in the app.

  • description

    string, max 500

    Shown on the collection page.

  • fieldDefinitions

    array of { key, label, type, options?, required? }

    Custom fields. Omit to use the type's standard fields.

update_collection

Write

Renames a collection, changes its description or replaces its field definitions. Anything you do not send stays as it is.

  • collectionIdRequired

    uuid

    Collection to change.

  • name

    string, 1-100

    New name.

  • description

    string, max 500

    New description.

  • fieldDefinitions

    array of { key, label, type, options?, required? }

    Replaces the whole field list.

create_items

Write

Adds up to 50 items in one call. Custom field values are checked against the collection's fields first; if any item is invalid, nothing is saved.

  • collectionIdRequired

    uuid

    Collection to add to.

  • itemsRequired

    array, 1-50 items

    The items to create.

  • items[].nameRequired

    string, 1-200

    Item name.

  • items[].description

    string, max 1000

    Free-text notes.

  • items[].quantity

    integer 1-999

    How many copies you own.

  • items[].customFieldValues

    object: field key -> string | number | boolean | null

    Values keyed by the collection's field keys (read the collection first to get them). Unknown keys are rejected with the list of valid ones.

  • items[].forSale

    boolean

    Lists the item for sale.

  • items[].salePrice

    integer (whole currency units) | null

    Asking price in whole units, e.g. 40 for $40.

  • items[].saleCurrency

    currency code, e.g. USD, EUR, UAH

    Currency of the sale price. Defaults to USD.

  • items[].completeness

    complete | incomplete | partial | sealed | unknown | null

    Whether the item is complete, sealed and so on.

  • items[].barcode

    string, max 64 | null

    EAN, UPC or ISBN.

  • items[].coverUrl

    https URL | null

    Link to a cover image. Stored as a link, not uploaded.

update_item

Write

Changes only the fields you send. Custom fields merge by key, and null clears a field. Set forSale with salePrice to list an item.

  • itemIdRequired

    uuid

    Item to change.

  • name

    string, 1-200

    New name.

  • description

    string, max 1000

    Free-text notes.

  • quantity

    integer 1-999

    How many copies you own.

  • customFieldValues

    object: field key -> string | number | boolean | null

    Values keyed by the collection's field keys (read the collection first to get them). Unknown keys are rejected with the list of valid ones.

  • forSale

    boolean

    Lists the item for sale.

  • salePrice

    integer (whole currency units) | null

    Asking price in whole units, e.g. 40 for $40.

  • saleCurrency

    currency code, e.g. USD, EUR, UAH

    Currency of the sale price. Defaults to USD.

  • completeness

    complete | incomplete | partial | sealed | unknown | null

    Whether the item is complete, sealed and so on.

  • barcode

    string, max 64 | null

    EAN, UPC or ISBN.

  • coverUrl

    https URL | null

    Link to a cover image. Stored as a link, not uploaded.

Delete

Permanent. Need the delete permission (off unless you tick it), have a separate small daily budget, and assistants are told to call them only when you ask.

delete_collection

Delete

Deletes a collection and every item in it. Refuses unless confirmName matches the collection's exact name.

  • collectionIdRequired

    uuid

    Collection to delete.

  • confirmNameRequired

    string (the collection's exact name)

    Must equal the collection's name exactly.

delete_items

Delete

Deletes up to 25 items from one collection.

  • collectionIdRequired

    uuid

    Collection the items belong to.

  • itemIdsRequired

    array of uuid, 1-25

    Ids of the items to delete.

Permissions and limits

When you click Allow, you choose what the assistant may do. You can see and disconnect every connected app in Owlect under Settings -> Connected apps.

read

See your collections and items. Always on.

create

Add collections and items. On by default.

update

Change collections and items. Off unless you tick it.

delete

Delete collections and items. Off unless you tick it.

Limits per connected app

  • 120 tool calls per minute.
  • 500 changes per day.
  • 20 delete calls per day. Anything more has to be done in the Owlect app.
  • Across all the apps you connect together: 1000 changes and 40 delete calls per day.
  • Up to 50 items per create_items call and 25 per delete_items call.
  • Your plan's item and collection limits apply exactly as in the app.

What the connector cannot do

  • Change sharing: make a collection public or private, or reset its link.
  • Touch your account, profile, email settings, billing or plan.
  • Upload photos. It can store a link to an image, but it cannot upload files.
  • See anyone else's collections.

Security and privacy

  • You sign in on owlect.app with Google. Your assistant never sees your Google password or your Owlect session.
  • The consent screen names the web address the app will send you back to. Owlect marks apps it has not verified. Only allow apps you started connecting yourself.
  • Access tokens last 1 hour and are renewed automatically. Owlect stores only a hash of each token.
  • Disconnecting an app in Settings -> Connected apps stops it immediately, including tokens it already holds.
  • Deletes are permanent. Assistants are told to delete only when you ask, and collection deletes need the exact collection name.

Troubleshooting

The sign-in window says "This connection link doesn't work".

The connection request was incomplete or came from an app Owlect does not know. Remove the connector in your assistant and add it again.

The assistant says it is not authenticated, or asks me to reconnect.

The app was disconnected in Settings, or its sign-in expired. Reconnect it from the assistant's connector settings.

"This connection is not allowed to update" (or create, or delete).

You did not tick that on the consent screen. Disconnect the app in Settings -> Connected apps and connect again, ticking what it should be able to do.

"Unknown field" errors when adding items.

Each collection has its own fields. Ask the assistant to check the collection's fields first. It gets the valid keys in the error too.

Item or collection limit reached.

The same plan limits apply as in the app. See your usage with get_account, and upgrade or invite friends for more room.

My changes do not show in the open Owlect tab.

Reload the page. Changes made by an assistant show up after a refresh.

Cursor (or another client) fails to sign in.

Use the mcp-remote setup above. Clients that sign in through a custom URL scheme are not accepted directly.

Technical reference

For developers building or debugging a client.

MCP endpoint
https://owlect.app/api/mcp
Transport
Streamable HTTP, stateless (no sessions). JSON-RPC 2.0.
Protected resource metadata (RFC 9728)
https://owlect.app/.well-known/oauth-protected-resource/api/mcp
Authorization server metadata (RFC 8414)
https://owlect.app/.well-known/oauth-authorization-server
Dynamic client registration (RFC 7591)
POST https://owlect.app/api/oauth/register. Public clients only (token_endpoint_auth_method: none). Redirect URIs must be https, or http on localhost.
Authorization endpoint
https://owlect.app/oauth/authorize
Token endpoint
POST https://owlect.app/api/oauth/token
Revocation (RFC 7009)
POST https://owlect.app/api/oauth/revoke
PKCE
Required, S256 only.
Scopes
read, create, update, delete
Token lifetimes
Access 1 hour, refresh 30 days and rotated on every use. Reusing a spent refresh token revokes the whole chain.
Unauthenticated requests
401 with WWW-Authenticate: Bearer ... resource_metadata="..." pointing at the protected resource metadata.