Skip to main content

MCP and assistant connections

Jawwws Bytes provides a hosted Model Context Protocol endpoint for compatible assistants and MCP clients.

https://api.jaww.ws/mcp

The hosted connection uses Bytes sign-in and delegated OAuth authorisation. You do not create or paste a workspace Developer API key into the assistant.

For practical setup steps, including ChatGPT and Claude, see the User Guide.

Client status​

Bytes distinguishes between clients that have completed Bytes-specific production verification and clients that are compatible with the remote MCP connection pattern but have not yet completed a Bytes smoke test.

Verified with Bytes​

These clients have been connected to the production Bytes MCP endpoint and exercised against supported Bytes workspace tools.

For ChatGPT, direct MCP production verification does not mean Bytes is already published in the OpenAI Plugins Directory. That separate distribution channel remains pending.

Compatible MCP clients​

  • Cursor
  • Perplexity
  • GitHub Copilot / VS Code
  • Windsurf
  • Gemini CLI
  • JetBrains AI Assistant

Compatible means the client supports the remote MCP transport/authentication pattern Bytes exposes. It does not mean Jawwws has completed a client-specific production smoke test, marketplace listing or partnership.

Client capabilities and setup screens can change independently of Bytes. If a compatible client does not complete the OAuth flow or expose the expected tools, use the current client documentation and the troubleshooting guidance below before treating it as Bytes-verified.

Connect to Bytes​

In a client that supports custom remote MCP servers:

  1. Add https://api.jaww.ws/mcp as a remote MCP server using Streamable HTTP.
  2. Follow the Bytes sign-in and authorisation flow opened by the client.
  3. Choose the Bytes workspace the assistant should access.
  4. Review the requested permissions and approve the connection.
  5. Return to the client and use the available Bytes tools.

Each connection is tied to the user who approved it, one selected workspace and the permissions approved for that grant.

Permissions​

Bytes uses these MCP permission scopes:

ScopeAllows
bytes:readRead supported Links, Link QR files, Activity Groups and Tags
bytes:links:writeCreate, update and archive supported Links
bytes:tags:writeCreate, update, delete, attach and detach Tags

Read access is required alongside either write scope.

Workspace role remains authoritative. Owners, Admins and Members can approve the supported read and write permissions. Viewers are read-only. If a user's workspace role is reduced after approval, an existing unexpired grant is narrowed immediately on its next use.

Current tool surface​

Read tools​

  • bytes_list_activity_groups
  • bytes_list_links
  • bytes_get_link
  • getQR
  • bytes_list_tags

getQR retrieves the governed standard QR for an existing Link through GET /api/v1/links/{id}/qr. It accepts the stable public link_id, optional format (png, svg or pdf) and optional PNG-only size.

PNG and SVG responses are returned as MCP image content with a text metadata item preserving the filename and MIME type. PDF responses use MCP embedded binary resource content, again with filename and MIME type metadata. The MCP adapter does not render QR codes itself.

  • bytes_create_link
  • bytes_update_link
  • bytes_archive_link

Tag write tools​

  • bytes_create_tag
  • bytes_update_tag
  • bytes_delete_tag
  • bytes_attach_tag
  • bytes_detach_tag

The Bytes Developer API remains authoritative for workspace isolation, plan entitlements, link limits, destination safety, validation and protected-record behaviour.

Analytics and Offline Engagement tools are not part of the current MCP surface because those operations are not yet in the maintained public Developer API contract.

OAuth and token behaviour​

The hosted endpoint uses OAuth authorisation code flow with PKCE S256 and public client metadata discovery.

MCP credentials and ordinary Bytes Developer API keys are separate credential families. An MCP access token is accepted only by the MCP resource. The runtime obtains a separate, very short-lived delegated Developer API credential for the authorised workspace and scopes when it calls /api/v1/*.

Existing jb_live_ Developer API keys continue to work unchanged for normal server-side Developer API integrations.

Revoke a connection​

Open Profile & Preferences > Security > Connected assistants in Bytes. Find the connection and choose Revoke access.

Revocation takes effect immediately for that assistant connection. It does not revoke Developer API keys and it does not sign you out of browser sessions.

Troubleshooting​

The client receives 401 before authorisation​

An unauthorised request to the MCP endpoint is expected to return an OAuth challenge. A compatible client should use the advertised discovery metadata and start the Bytes authorisation flow.

Write tools are missing​

Check the scopes approved for the connection and your current role in the selected workspace. Viewer access is read-only. A role downgrade can also remove write tools from an existing connection immediately.

A previously working connection stops working​

The grant may have been revoked, the user's workspace access may have changed, or the OAuth token may need to be refreshed. Reconnect through the client if it cannot recover through its normal OAuth refresh flow.

The wrong workspace was authorised​

Revoke the connection in Connected assistants, then connect again and select the intended workspace. A grant does not silently switch workspaces.

The client asks for a Bytes API key​

The supported hosted OAuth connection at https://api.jaww.ws/mcp does not require a customer workspace API key. Do not paste an API key into prompts or tool arguments.

Distribution status​

Direct connection to the production remote endpoint is supported for compatible MCP clients.

Bytes is also listed in the official MCP Registry as:

io.github.jawwws/bytes
version 0.2.0

The Registry listing is a discovery channel. The supported connection remains https://api.jaww.ws/mcp.

Bytes is not currently available in the OpenAI Plugins Directory. That distribution channel remains pending business verification, submission, review and publication.

Last updated on