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.

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, 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
  • bytes_list_tags
  • 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. Official directory and marketplace listings are separate publication channels and may have their own review or rollout timing.

Last updated on