Personal context API for AI tools and apps

Personal context for your application

Project Fingerprint provides a JSON API for personal profiles, preferences, and taste data, including reviewed updates. Build recommendations and planning tools around the context a person has approved for your connection. Use standard HTTP requests from a backend service or native app.

The API and hosted MCP server are two ways to access the same approved context. Choose the API for JSON integration or MCP for a client that speaks Model Context Protocol.

What you can read

• Personal profile: get_profile_context reads approved sections; get_profile_template returns public starter headings.
• Preferences: get_taste_summary, search_taste, get_connections, and get_boundaries return selected taste information.
• Task context: get_context_for_task returns relevant approved taste context. evaluate_candidates compares supplied candidates and requires separate opt-in permission.
• Freshness and access: get_recent_changes and get_connection_status help check the shared copy and connection.
• Catalog: search_catalog finds public items within permitted domains; it requires the existing taste suggestion or write scope.

The API also reads update status. Its sixteen operations share the MCP handlers and permissions. The OpenAPI reference lists each operation’s inputs, outputs, and required scopes.

Propose and follow up on updates

With suggestion permission, send one exact batch to propose_fingerprint_update, or use propose_profile_update and suggest_map_update. Include current revisions for existing edits. Each change must fit the approved sections, domains, and scopes. A pending_review response includes a link for the owner to review in Fingerprint.

Only after the owner requests saving that exact batch, and the connection permits writing, call save_fingerprint_update with its update ID. queued means awaiting application while Fingerprint is unlocked and online. Check get_fingerprint_update_status; only applied means saved. Conflicts require review. New sections stay private until approved for sharing.

Set up approved access

1. The profile owner signs in to Fingerprint, unlocks their account, and opens Connect AI → Add connection.
2. Choose API / MCP, select the profile sections and taste data to share, then select Preview sharing.
3. Review the copy, continue, name the connection, select OAuth, and create the connection.
4. Your application completes OAuth authorization with PKCE S256 and its registered callback. The owner selects the connection and approves the requested access. Request only the scopes your application needs. Check the token response’s scope list: the owner’s connection may permit a smaller subset.

The API requires OAuth. An owner’s session cookie or a manual MCP secret URL does not authorize JSON API requests.

OAuth discovery

Use the protected resource metadata and authorization server metadata to discover registration, authorization, token, and revocation endpoints.

The OAuth resource is https://projectfingerprint.com/mcp, including for API requests. Register your exact callback and use authorization code flow with PKCE S256. Access is limited by both the token’s scopes and the owner-approved connection.

On refresh, scope can narrow the new access token. The rotated refresh token retains its original approval; omitting scope requests that original set again. Additional unapproved scopes return invalid_scope. Check the scope in every token response.

Use your HTTPS URL as a client ID

Public API and MCP clients can host a client metadata document at an HTTPS URL with a non-root path, such as https://your-app.example/oauth/client.json. Serve JSON containing client_id matching that URL exactly, client_name, redirect_uris, and token_endpoint_auth_method: "none". Use that URL as your OAuth client ID.

Callbacks must match exactly and use HTTPS or HTTP on localhost, 127.0.0.1, or [::1]. The metadata URL must be publicly reachable and return JSON directly. Fingerprint retrieves it during each consent review and approval; unavailable or changed metadata requires a new attempt. Keep the document available throughout onboarding. Dynamic registration is also supported through the discovered registration endpoint.

Example: read an approved profile

With an OAuth access token carrying profile:read, send an empty JSON object to read all profile sections approved for this connection. This example uses an unbound Bearer token; replace the placeholder with the token from your OAuth flow.

POST /mcp/v1/get_profile_context HTTP/1.1
Host: projectfingerprint.com
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
Content-Type: application/json

{}

Device-bound tokens instead require Authorization: DPoP and a fresh ES256 DPoP proof. Sign the actual request URL and POST method with the bound key, including the access-token hash, a unique proof ID, and the current time. Never substitute Bearer authorization for a bound token.

TypeScript and Python clients

Download the small TypeScript client for Node.js 22+ or Python 3.10+ client. Both use standard libraries with no added dependencies. Copy the file into your application and supply credentials from your OAuth integration. For bound tokens, also supply a signer for fresh DPoP proofs.

Use read(operation, input) for reads or request(operation, input) for any permitted operation, including updates. Your application handles OAuth callbacks, secure token and key storage, and token refresh. These clients send JSON requests with a 30-second timeout; they do not store credentials, follow redirects, or retry automatically.

Provider errors retain their HTTP status and OAuth challenge: FingerprintError.wwwAuthenticate in TypeScript, or FingerprintError.www_authenticate in Python. Pass that challenge to your OAuth integration. Additional scopes require the owner’s approval; a revoked connection requires restored authorization before further reads.

For a file-based starting point, download the blank Markdown profile template. It contains starter questions and no personal data.

Handle permissions and freshness

Responses contain only the approved shared copy, which may be older than the local profile. Check update times; the owner refreshes the copy with Fingerprint unlocked and online. New sections stay private until approved. Pausing or revoking the connection stops future reads but cannot recall copies already received.

Use HTTP status codes to handle failures: 401 means invalid or missing access, 403 means the operation is not permitted, and 409 means access or context changed during the request. A 403 with insufficient_scope identifies scopes for a new consent request. A 403 without that challenge can reflect the owner’s connection restrictions. Check the issued scope before retrying; partial approval must not trigger repeated consent requests.

Send application/json; request bodies are limited to 16 KiB. See sharing controls for the owner’s permissions.

Choose your integration

API: approved reads and update requests as JSON for backend services and native apps. Third-party browser origins cannot assume direct CORS access.

MCP server: tools for compatible AI clients, including separately permitted suggestions and saves.

Browser WebMCP: tools in an approved open tab. Markdown: a portable snapshot you export from your profile. These integrations do not automatically synchronize an assistant’s built-in memory.